콘텐츠 레지스트리

콘텐츠 레지스트리는 게임 내 맵, 아이템, 스킬 등의 정적 메타데이터를 관리하고 텔레메트리 데이터와 연결하는 기능입니다.

왜 필요한가

범용 텔레메트리 도구에서는 이벤트 데이터에 포함된 ID가 무엇을 의미하는지 알 수 없습니다. 콘텐츠 레지스트리를 사용하면:

• item_id: "sword_01" → “불꽃의 검 (레어 / 무기 카테고리)”
• map_id: "map_desert" → “사막 아레나 (PvP 맵)”

텔레메트리에 게임 컨텍스트를 부여하여 의미 있는 분석이 가능해집니다.

콘텐츠 유형

유형	설명	예시
map	게임 맵	스테이지, 아레나, 월드
item	게임 내 아이템	무기, 소모품, 장비
skill	스킬/어빌리티	공격, 버프, 패시브
character	캐릭터	플레이어블, NPC
custom	커스텀 정의	임의의 게임 요소

데이터 동기화

콘텐츠 레지스트리의 데이터는 게임의 마스터 데이터와 동기화됩니다.

수동 등록

대시보드에서 개별적으로 등록하거나 REST API로 등록합니다. POST /v1/content 엔드포인트는 X-Project-Id 헤더를 필수로 요구하며 엔트리를 entries 엔벨로프로 감쌉니다:

curl -X POST https://app.framedash.dev/api/v1/content \
  -H "X-API-Key: fd_your_api_key_here" \
  -H "X-Project-Id: your-project-uuid" \
  -H "Content-Type: application/json" \
  -d '{
    "entries": [
      {
        "contentType": "item",
        "contentId": "item_hp_01",
        "displayName": "Health Potion",
        "metadata": { "rarity": "common", "category": "consumable" }
      }
    ]
  }'

일괄 가져오기 (권장)

CI 파이프라인에서 CLI를 사용하여 마스터 데이터를 JSON으로 일괄 가져옵니다. CLI는 엔트리의 순수 JSON 배열을 받습니다 (entries 엔벨로프 불필요):

framedash content import ./game-content.json

game-content.json 형식:

[
  {
    "contentType": "item",
    "contentId": "item_hp_01",
    "displayName": "Health Potion",
    "metadata": { "rarity": "common", "category": "consumable" }
  }
]

각 엔트리에는 contentType, contentId, displayName이 필수이며 metadata는 선택 사항입니다.

텔레메트리와의 연동

SDK에서 이벤트를 전송할 때 해당 콘텐츠 ID(contentId에 대응하는 map_id, item_id 등)를 포함하면 대시보드에서 콘텐츠 이름과 메타데이터가 자동으로 표시됩니다.

다음 단계

• API 레퍼런스: 콘텐츠 레지스트리 API
• CLI 레퍼런스: 데이터 동기화 명령어