内容注册表

内容注册表是管理游戏中地图、物品、技能等静态元数据，并将其与遥测数据关联的功能。

为什么需要它

通用遥测工具无法理解事件数据中 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 参考: 数据同步命令