直接 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` scope を持つ 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" } を返します。これは、各イベントが後段の検証を通過したことや永続ストレージへ保存されたことの確認ではありません。デコード可能なバッチでも、無効なイベントは後から破棄されることがあります。

取り込まれたイベントが builds やクエリ、ダッシュボードに反映されるまでには 20〜30 秒ほどかかります。すぐに表示されなくても取り込みが失敗したわけではありません。独自送信のエンドツーエンド確認では、1 件のイベントに ingest_probe_<unique-id> のような一意のマーカーを付け、<unique-id> を実行ごとに UUID などへ置き換えます。待機後に data:admin scope を持つ Full キーでそのマーカーを正確にクエリします。Read-only キーの analytics:read scope では集計 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>'"

件数が 1 以上で、最大時刻が今回の実行時刻と一致する場合にだけ永続保存を確認できます。過去のテストイベントを誤検出しないよう、テストごとに新しいマーカーを使ってください。

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;
}

送信例

.proto を protoc（または buf）でコンパイルし、生成コードで TelemetryBatch を組み立ててバイト列にシリアライズします。シリアライズしたバイト列をファイルに書き出し、curl の --data-binary で POST します。

# 1. proto をコンパイル（例: Python）
protoc --python_out=. telemetry.proto

# 2. アプリのコードで TelemetryBatch を組み立て、batch.bin へ書き出す

# 3. POST する
curl -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 は空でないこと、文字列やマップの各フィールドは上限内であること、数値メトリクスは有限であることが求められます。公式 SDK はこれらの値を送信前にクランプします。

次のステップ

イベントスキーマ: クエリで返るカラム
API 概要: 認証とレスポンス形式
トラブルシューティング: イベント到達の確認

AI エージェント向け: llms.txt