Unity SDK

Framedash Unity SDK를 사용하여 퍼포먼스 텔레메트리를 자동으로 수집하는 방법을 설명합니다.

요구 사항

Unity 2022.3 이상
.NET Standard 2.1 / .NET Framework 4.x

설치

Unity Package Manager (권장)

Window > Package Manager를 엽니다
”+” > “Add package from git URL…”을 선택
다음 URL을 입력합니다:

https://github.com/crane-valley/framedash-unity-sdk.git

특정 릴리스로 고정하려면 버전 태그를 추가합니다:

https://github.com/crane-valley/framedash-unity-sdk.git#v0.1.0

초기 설정

시작 시 SDK를 한 번 초기화합니다. 예를 들어 항상 유지되는 GameObject의 MonoBehaviour에서 초기화합니다:

using System.Collections.Generic;
using Framedash;
using UnityEngine;

public sealed class GameBootstrap : MonoBehaviour
{
    // API 키는 Inspector에서 설정하거나 ScriptableObject 또는 플랫폼 시크릿
    // 저장소에서 로드하세요. 환경 변수는 모바일/콘솔/WebGL에서 사용할 수 없으므로
    // Environment.GetEnvironmentVariable는 사용하지 않습니다.
    [SerializeField] private string _apiKey;

    private void Awake()
    {
        TelemetrySDK.Initialize(
            apiKey: _apiKey,
            buildId: Application.version);
    }
}

endpointUrl은 선택 사항이며 생략 시 https://ingest.framedash.dev/v1/events가 사용됩니다. 로컬 또는 자체 호스팅 ingest를 지정하려면 명시적으로 전달하세요.

퍼포먼스 데이터 자동 수집

SDK는 다음 데이터를 자동으로 수집합니다:

FPS — 프레임 레이트
Frame Time — 프레임당 처리 시간
Memory — 매니지드 힙 + 네이티브 메모리 사용량

커스텀 이벤트 전송

TelemetrySDK.Instance.Track(
    eventName: "player_death",
    mapId: "map_01",
    position: transform.position);

범주형 속성이나 수치 메트릭을 첨부하려면 선택적 딕셔너리를 전달합니다:

TelemetrySDK.Instance.Track(
    eventName: "player_death",
    mapId: "map_01",
    position: transform.position,
    attributes: new Dictionary<string, string> { { "cause", "fall_damage" } },
    metrics: new Dictionary<string, float> { { "health", 0f } });

플레이어 식별 (선택)

기본적으로 이벤트는 익명으로 전송됩니다. 플레이어가 로그인한 후 SetPlayerId를 호출하면 이후 이벤트가 해당 플레이어와 연결됩니다:

TelemetrySDK.Instance.SetPlayerId(playerId);

다음 단계

데이터 모델 — 텔레메트리 데이터의 구조
히트맵 — 수집된 데이터의 시각화