資料模型
說明 Framedash SDK 收集與傳送的遙測資料結構。
每個事件都是一個 GameTelemetryEvent，以 Protobuf 序列化後透過 TelemetryBatch 傳送至 POST /v1/events。每個事件對應 ClickHouse events 資料表中的一列。結構描述是固定的（於 telemetry.proto 定義）；遊戲專屬資料可存放在彈性的 attributes / metrics 對應中，但值必須維持在下方的攝取限制內。
識別與內容脈絡
Section titled “識別與內容脈絡”| 欄位 | 型別 | 說明 |
|---|---|---|
event_name | string | 事件識別碼，例如 player_death，或自動事件 session_start / perf_heartbeat。 |
timestamp_us | int64 | 事件發生時間（Unix epoch 微秒，以 DateTime64(6) 儲存）。 |
session_id | string | 遊戲工作階段識別碼。 |
player_id | string | 明確的玩家識別碼。SDK 收集的唯一 PII。COPPA 模式下會被清除。 |
map_id | string | 用於空間分析的地圖 / 關卡識別碼。 |
build_id | string | 建置版本。 |
platform | string | 引擎回報的平台名稱（Unity 為 Application.platform，UE 為 IniPlatformName，Godot 為 OS.GetName()）。 |
engine_version | string | 引擎版本（Unity 為 Application.unityVersion，UE 為 FEngineVersion，Godot 為 Engine.GetVersionInfo()["string"]）。 |
source | enum | 事件來源：player / automated / unspecified。 |
位置與攝影機
Section titled “位置與攝影機”| 欄位 | 型別 | 說明 |
|---|---|---|
position | Vector3（x、y、z 浮點數） | 世界空間位置。以 position_x / position_y / position_z 儲存。 |
camera_yaw | float（選填） | 攝影機水平旋轉（度）。0 = 正北，順時針，範圍 [0, 360)。當 SDK 不擷取攝影機時不存在。 |
camera_pitch | float（選填） | 攝影機垂直旋轉（度）。-90 = 正下方，+90 = 正上方。 |
camera_yaw 與 camera_pitch 會一起傳送，或完全不傳送。缺少該值表示「未擷取」，而非 0。
由 SDK 自動收集，特別是在每 10 秒傳送一次的 perf_heartbeat 事件中：
| 欄位 | 型別 | 單位 / 備註 |
|---|---|---|
fps | float | 每秒影格數 |
frame_time_ms | float | 毫秒 |
gpu_time_ms | float | 毫秒 |
game_thread_ms | float | CPU 遊戲執行緒時間（ms）。0 = 未收集 |
render_thread_ms | float | CPU 算繪執行緒時間（ms）。0 = 未收集 |
memory_used_bytes | int64 | 位元組 |
載入耗時與磁碟 I/O 指標
Section titled “載入耗時與磁碟 I/O 指標”Unity SDK 0.1.3、UE5 SDK 0.1.6 和 Godot SDK 0.1.4 新增了兩項自動收集的效能訊號。兩者都會進入 perf-diff（建置比對）迴歸閘門和儀表板圖表。
map_load：由BeginMapLoad/EndMapLoad或ReportMapLoad在地圖或關卡載入完成時發出的專用自動事件。它攜帶metrics["load_time_ms"]與attributes["map_name"]，並刻意將map_id留空，從而不進入空間熱力圖和啟用閘門。io.read_bytes/io.read_time_ms/io.read_ops：以相對上一次 heartbeat 的增量附加到perf_heartbeat的metrics對應的磁碟讀取計數器。只有在真正擷取到樣本之後才會出現。自動來源在 Unity 上僅限 Editor / Development Build（AsyncReadManagerMetrics），在 UE5 上為選擇性開啟（bTrackDiskIo），在 Godot 上僅限手動（ReportIoSample）。
各引擎的 API 和執行緒規則見各 SDK 指南。
記憶體分類指標
Section titled “記憶體分類指標”受支援的 SDK 會把各記憶體分類的用量作為 mem.* 指標附加到 perf_heartbeat 和帶位置的事件上。可用的鍵與收集方式因引擎而異。
- UE5 SDK 0.1.7 及更新版本：
mem.vram以及依賴 LLM 的mem.textures/mem.meshes/mem.audio。三者都需要 opt-in（bTrackMemoryDetail，預設關閉）；mem.vram無需 LLM，但在無頭 /-nullrhi執行中不會附加（此時是鍵缺失，而非0）。 - Unity SDK 0.1.4 及更新版本：
mem.vram和mem.heap。自動收集，無需 opt-in。 - Godot SDK 0.1.5 及更新版本：
mem.vram、mem.textures和mem.buffers。自動收集，無需 opt-in。
三者都放在 metrics 對應中，未追蹤的分類會讓該鍵缺失（表示「未收集」，與已收集的 0 不同）。mem.vram 同時也是 perf-diff（建置比對）的比較指標。各引擎細節見 UE5 SDK、Unity SDK 和 Godot SDK 指南。
遊戲專屬內容脈絡透過兩個彈性對應傳送，無需變更結構描述：
| 欄位 | 型別 | 說明 |
|---|---|---|
attributes | map<string, string> | 字串鍵值對，例如 weapon: "rifle"。COPPA 模式下整體捨棄。 |
metrics | map<string, double> | 數值量測值，例如 damage: 42.5。 |
攝取驗證限制
Section titled “攝取驗證限制”攝取管線會驗證每個解碼後的事件。如果批次中任何一個事件超出這些限制，該批次可能在請求時被拒絕，或在非同步處理期間被整體丟棄。因此，自訂 SDK 和原始 Protobuf 傳送方應在 flush 前鉗制取值。官方 Unity、UE5 與 Godot SDK 會在用戶端套用這些鉗制。
| 欄位 | 限制 |
|---|---|
timestamp_us | 必須在過去 30 天內，且不得超過未來 48 小時。 |
event_name / session_id | 必填且不可為空。event_name 最多 128 個字元，session_id 最多 64 個字元。 |
player_id, map_id, build_id | 各最多 128 個字元。 |
source, platform, engine_version | 各最多 64 個字元。 |
position_x / position_y / position_z | 必須是有限數字，絕對值不超過 1e9。 |
fps | 0 到 1000 之間的有限數字。 |
frame_time_ms / gpu_time_ms / game_thread_ms / render_thread_ms | 0 到 10000 之間的有限毫秒值。 |
memory_used_bytes | 0 到 64 GiB 之間的整數。 |
attributes | 最多 50 個項目；key 最多 64 個字元；value 最多 512 個字元。 |
metrics | 最多 50 個項目；key 最多 64 個字元；value 必須是有限數字。 |
camera_yaw / camera_pitch | 必須同時存在或同時省略。yaw 正規化為 [0, 360)，pitch 正規化為 [-90, 90]。 |
SDK 傳送 TelemetryBatch（即 GameTelemetryEvent 清單）。API 金鑰與 SDK 版本透過 HTTP 標頭（X-API-Key、X-SDK-Version）傳輸，而非放在酬載內文中。
自訂傳送方應將傳送時的 HTTP 請求本文（若使用 gzip，則為壓縮後）維持在 126,000 bytes 以內。生產攝取會以 413 拒絕更大的本文；官方 SDK 會在明顯低於該上限時 flush。