內容註冊表

內容註冊表是管理遊戲中地圖、道具、技能等靜態中繼資料，並將其與遙測資料建立關聯的功能。

為什麼需要

通用遙測工具無法辨識事件資料中 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 參考: 資料同步指令