直接 HTTP 擷取 (protobuf)
若要在不使用官方 SDK 的情況下傳送遙測資料，請將 protobuf 編碼的 TelemetryBatch 直接 POST 到擷取端點。
大多數整合應改用官方的 Unity、UE5 或 Godot SDK。
本頁面向沒有 SDK 的引擎，或擁有自建傳送管線的團隊，提供底層的接入方式。
| 項目 | 值 |
|---|---|
| 方法與 URL | POST https://ingest.framedash.dev/v1/events |
Content-Type | application/x-protobuf |
X-API-Key | 擁有 events:write 範圍的 Ingest 金鑰 |
X-SDK-Version | SDK 版本識別碼（例如 custom-1.0.0） |
Content-Length 必須與實際請求主體大小一致。
若對請求主體進行 gzip 壓縮，請加上 Content-Encoding: gzip。
請將請求主體（若使用 gzip，則為壓縮後）保持在 126,000 位元組以內。
超出則以 413 拒絕。
非 application/x-protobuf 的 Content-Type，或非 gzip 的 Content-Encoding，會回傳 415。
缺少 Content-Length 會回傳 411。
端點在接受批次進行非同步處理後回傳 202 及 { "status": "accepted" }。
這並不確認每個事件都通過後續驗證或已持久化儲存；可解碼的批次仍可能包含之後會被捨棄的無效事件。
擷取到的事件需要約 20~30 秒才會出現在 builds、查詢與儀表板中。
短暫延遲並不代表擷取失敗。
對自訂傳送器進行端對端檢查時，請為一個事件設定如 ingest_probe_<unique-id> 的唯一標記，並在每次執行時將 <unique-id> 替換為 UUID 等值。等待後再用擁有 data:admin 範圍的 Full 金鑰精確查詢該標記。Read-only 金鑰的 analytics:read 範圍可以存取彙總分析 API，但不能執行此處使用的 raw SQL framedash query：
framedash query --api-key-file full.key --project-id <project-id> \ "SELECT count(), max(timestamp) FROM events WHERE event_name = 'ingest_probe_<unique-id>'"只有計數大於零且最大時間戳記來自本次執行，才能確認持久化儲存。每次測試都應使用新標記，以免舊的測試事件造成誤判。
proto3 結構描述
Section titled “proto3 結構描述”請求主體是編碼後的 framedash.v1.TelemetryBatch 訊息（proto3）的位元組字串。
api_key 與 sdk_version 透過 HTTP 標頭（X-API-Key、X-SDK-Version）傳輸，而不放在酬載中。
完整的結構描述定義如下。
syntax = "proto3";
package framedash.v1;
// 3D position vector for spatial analytics (heatmaps, player tracking).message Vector3 { float x = 1; float y = 2; float z = 3;}
// Source of the telemetry event.enum TelemetrySource { TELEMETRY_SOURCE_UNSPECIFIED = 0; TELEMETRY_SOURCE_PLAYER = 1; TELEMETRY_SOURCE_AUTOMATED = 2;}
// Core telemetry event emitted by game SDKs.// Each event maps to a single row in the ClickHouse `framedash.events` table.message GameTelemetryEvent { string event_name = 1; // Unix epoch in microseconds. Stored as DateTime64(6) in ClickHouse. int64 timestamp_us = 2; string session_id = 3; // Explicit player identifier — the only PII the SDK may collect. string player_id = 4; Vector3 position = 5; string map_id = 6; reserved 7; reserved "zone_id"; float fps = 8; float frame_time_ms = 9; int64 memory_used_bytes = 10; float gpu_time_ms = 11; // Free-form string key-value pairs for game-specific context. map<string, string> attributes = 12; // Free-form numeric metrics for game-specific measurements. map<string, double> metrics = 13; // Source of the telemetry event. TelemetrySource source = 14; string build_id = 15; string platform = 16; string engine_version = 17; // Camera orientation in degrees. // camera_yaw: horizontal rotation (0 = North, clockwise, [0, 360)). // camera_pitch: vertical rotation (-90 = straight down, +90 = straight up). // 'optional' enables has-field presence tracking — distinguishes // "not sent by SDK" (absent) from "facing North at level" (0, 0). optional float camera_yaw = 18; optional float camera_pitch = 19; // CPU game thread time in milliseconds (logic, AI, physics). // 0 = not collected (old SDK or unavailable). float game_thread_ms = 20; // CPU render thread time in milliseconds (draw commands, culling). // 0 = not collected (old SDK or unavailable). float render_thread_ms = 21;}
// Batch wrapper sent by SDKs via POST /v1/events.// api_key and sdk_version are transmitted in HTTP headers (X-API-Key, X-SDK-Version),// not in the Protobuf payload.message TelemetryBatch { repeated GameTelemetryEvent events = 1;}用 protoc（或 buf）編譯 .proto，用產生的程式碼建立 TelemetryBatch 並序列化為位元組。
將序列化後的位元組寫入檔案，再用 curl --data-binary POST。
# 1. 編譯 proto（以 Python 為例）protoc --python_out=. telemetry.proto
# 2. 在應用程式碼中建立 TelemetryBatch 並寫入 batch.bin
# 3. 送出 POSTcurl -X POST https://ingest.framedash.dev/v1/events \ -H "X-API-Key: fd_your_ingest_key_here" \ -H "X-SDK-Version: custom-1.0.0" \ -H "Content-Type: application/x-protobuf" \ --data-binary @batch.bin每個事件都必須滿足資料模型的攝取驗證限制。
timestamp_us 必須在最近 30 天內，且不超過未來 48 小時；event_name 與 session_id 不能為空；字串與 map 欄位必須在上限之內；數值指標必須為有限值。
官方 SDK 會在傳送前對這些值進行箝制。