TapDB 埋点入门指南

一、什么是埋点？为什么要埋点？

1.1 通俗理解

埋点就是在游戏里装"监控摄像头"。

想象一下，你在游戏里装了无数个隐形摄像头：

• 玩家进入了哪个关卡 → 记下来
• 玩家看了多长时间广告 → 记下来
• 玩家在第几关弃坑了 → 记下来

这些摄像头记录的数据，就是埋点数据。

1.2 埋点能帮我们做什么？

场景对比：

二、埋点设计：如何设计一个好的埋点方案？

2.1 核心原则

原则一：能合并就合并

很多新手喜欢一个动作一个事件，结果埋了几百个事件，自己都记不住。

AdSignIn        → 补签广告
AdDoubleIncome  → 翻倍广告
AdAddGuest      → 加客广告
AdGetRes        → 资源广告
...（还要继续吗？）

AdWatch（一个事件搞定）
  └── ad_type: sign_in / double_income / add_guest / get_res

用 ad_type 这个参数区分不同类型，一个事件解决所有广告场景！

原则二：属性名要统一

同一个东西，到处用不同的名字，分析时会崩溃。

事件A用：levelId、level_id、LevelID
事件B用：stageId、stage_id

所有事件统一用：level_id

原则三：命名要有规律

三、代码怎么写？实战教学

3.1 最重要的规则：井号前缀

{ "#level_id", "level_1" }
{ "#ad_type", "double_income" }

{ "level_id", "level_1" }

3.2 常见埋点代码示例

1. 简单事件（无参数）

// 用户登录成功
Analytics.Event("UserLogin");

// 游戏加载完成
Analytics.Event("FinishLoading");

2. 带参数的事件

// 开始关卡
Analytics.Event("StartLevel", new Dictionary()
{
    { "#level_id", "level_1" }
});

// 关卡详情（多参数）
Analytics.Event("LevelDetail", new Dictionary()
{
    { "#level_id", "level_1" },
    { "#result", "pass" },        // pass 或 fail
    { "#duration", 120 },         // 时长（秒）
    { "#income", 1000 }           // 收入
});

3. 复合事件（用 action 区分）

// 拼图游戏 - 开始
Analytics.Event("JigsawEvent", new Dictionary()
{
    { "#action", "start" },
    { "#jigsaw_id", 1 }
});

// 拼图游戏 - 完成
Analytics.Event("JigsawEvent", new Dictionary()
{
    { "#action", "finish" },
    { "#jigsaw_id", 1 }
});

四、后台操作：CSV 批量导入

4.1 准备 CSV 文件

TapDB 支持批量导入事件配置，格式如下：

event_name,event_desc,status,remark,bind_prop_names
StartLevel,开始关卡,display,关卡开始时触发,level_id
LevelDetail,关卡详情,display,每局结束时触发,level_id|result|duration|income
AdWatch,观看广告,display,观看广告时触发,ad_type|level_id|bonus_income

4.2 字段说明

4.3 上传步骤

1. 登录 TapDB 后台
2. 选择项目 → 事件管理 → 批量操作
3. 上传 CSV 文件
4. 确认导入

五、数据查询：SQL 实战

数据上报后，怎么查？用 SQL！

5.1 基础查询

-- 查询最近两天的关卡事件
SELECT *
FROM hive_saas1.tapdb."events"
WHERE "$part_date" IN ('2026-03-01', '2026-03-02')
  AND name IN ('LevelStart', 'LevelDetail')
LIMIT 10000

5.2 查询指定属性

SELECT
  name,
  data."#level_id" AS level_id,
  data."#result" AS result,
  data."#duration" AS duration
FROM hive_saas1.tapdb."events"
WHERE "$part_date" IN ('2026-03-01', '2026-03-02')
  AND name = 'LevelDetail'

5.3 计算关卡通过率

SELECT
  data."#level_id" AS level_id,
  SUM(CASE WHEN data."#result" = 'pass' THEN 1 ELSE 0 END) AS pass_count,
  SUM(CASE WHEN data."#result" = 'fail' THEN 1 ELSE 0 END) AS fail_count,
  ROUND(
    SUM(CASE WHEN data."#result" = 'pass' THEN 1 ELSE 0 END) * 100.0 / COUNT(*),
    2
  ) AS pass_rate
FROM hive_saas1.tapdb."events"
WHERE "$part_date" BETWEEN '2026-03-01' AND '2026-03-07'
  AND name = 'LevelDetail'
GROUP BY data."#level_id"

运行结果示例：

5.4 查询广告类型分布

SELECT
  data."#ad_type" AS ad_type,
  COUNT(*) AS event_count
FROM hive_saas1.tapdb."events"
WHERE "$part_date" BETWEEN '2026-03-01' AND '2026-03-07'
  AND name = 'AdWatch'
GROUP BY data."#ad_type"
ORDER BY event_count DESC

5.5 常用字段速查表

六、避坑指南

6.1 常见错误

6.2 最佳实践

1. 埋点前先设计：先列出需要分析的问题，再设计埋点方案
2. 命名要有文档：维护一份属性字典，团队共用
3. 上线前先测试：在后台验证数据是否正确上报
4. 定期清理：废弃的事件和属性及时清理

七、总结

事件命名 PascalCase    属性命名 snake_case
代码上报加井号          CSV 导入不加井号
相似事件用 action       属性复用要统一
查询记得加分区          数据驱动做决策

7.2 学习路线

参考资料

• TapDB 官方文档：https://developer.taptap.cn/docs/sdk/tapdb/
• 事件导入模板：见上文 CSV 格式