직접 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" }를 반환합니다. 이는 모든 이벤트가 후속 검증을 통과했거나 영구 스토리지에 저장되었다는 확인이 아닙니다. 디코딩 가능한 배치에도 나중에 폐기되는 잘못된 이벤트가 포함될 수 있습니다.

수집된 이벤트가 builds, 쿼리, 대시보드에 나타나기까지 약 20~30초가 걸립니다. 잠깐 지연된다고 해서 수집이 실패한 것은 아닙니다. 커스텀 전송기를 엔드투엔드로 확인하려면 한 이벤트에 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>'"

개수가 0보다 크고 최대 타임스탬프가 이번 실행 시각과 일치해야 영구 저장을 확인할 수 있습니다. 이전 테스트 이벤트로 인한 오탐을 막으려면 테스트마다 새 마커를 사용하세요.

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

각 이벤트는 데이터 모델의 Ingest 검증 제한을 충족해야 합니다. timestamp_us는 최근 30일 이내이고 48시간 넘게 미래여서는 안 되며, event_name과 session_id는 비어 있지 않아야 하고, 문자열과 맵 필드는 상한 내에 있어야 하며, 숫자 메트릭은 유한해야 합니다. 공식 SDK는 전송 전에 이 값들을 클램프합니다.

다음 단계

이벤트 스키마: 쿼리가 반환하는 컬럼
API 개요: 인증과 응답 형식
문제 해결: 이벤트 도착 확인

AI 에이전트용: llms.txt