# 数据统计

# 接口说明

用于上报并记录用户在游戏内的行为日志&事件(如:启动、登录、创角、充值等行为),方便观察数据的变化、快速定位问题的根源,以及追踪程序执行的过程等。

sdkInstance.trackEvent(eventId, eventParams);

# 参数说明

参数说明如下表所示:

选项 类型 必填 默认值 说明
eventId string 是 -- 事件ID
eventParams object 条件必填 -- 事件参数

# 数据上报

# 流程统计上报

上报相关流程统计数据(程序或游戏行为日志),在SDK初始化完成后即可调用。

注:示例代码中的参数或选项均为演示数据,仅供参考,谢谢!

// 事件ID
const eventId = "100100::SDK_CLIENT_LAUNCH"; // 表示SDK客户端上报的启动事件

// 事件参数
const eventParams = {};

// 必填参数
eventParams.logLevel = "d"; // 日志类型,必填;d 用于标记普通(成功)日志,e 用于标记异常(失败)日志
eventParams.logContent = "SDK启动"; // 日志内容,必填;可以是描述文本或JSON字符串等任意字符串,如程序执行错误信息或网络请求响应信息等

// 执行上报
sdkInstance.trackEvent(eventId, eventParams);

SDK及游戏侧需按照《微信小游戏日志上报埋点模板》 (opens new window)完成部分流程统计基础日志埋点,其他扩展日志请根据游戏业务需要或运营需求自行定义,本文档不做要求,谢谢!

注意事项

  • 事件ID格式为 六位数字::字符串,即 6 位纯数字 + 英文双冒号 + SDK或GAME + SERVER或CLIENT + 动作或事件标识;如 100100::SDK_CLIENT_LAUNCH 表示SDK客户端上报的启动事件;事件ID应确保同一游戏内全局唯一!
  • 包含 ::SDK_CLIENT 字符的事件由SDK客户端负责上报,如有疑问请联系对接人员:丁伟、王占伟;
  • 包含 ::SDK_SERVER 字符的事件由SDK服务端负责上报,如有疑问请联对接人员:邓泳辉、陈肖军;
  • 包含 ::GAME_CLIENT 字符的事件由游戏客户端负责上报,如有疑问请联系游戏客户端研发相关人员;
  • 包含 ::GAME_SERVER 字符的事件由游戏服务端负责上报,如有疑问请联系游戏服务端研发相关人员;
  • 事件参数 eventParams 必须包含 logLevel、logContent 字段,其中 logLevel 固定为 d 或 e。

# 游戏加载完成

当 loading 页面完成,游戏进到第一个用户可交互场景时上报(即游戏开始接收用户屏幕事件,如点击、滑动等)(2.4.4 版本新增)。

注:示例代码中的参数或选项均为演示数据,仅供参考,谢谢!

sdkInstance.trackEvent("gameready");

注意事项

  • 事件ID eventId 固定为 gameready,无需修改;
  • 以上事件将由SDK转发至腾讯广告平台,需在初始化时配置 tencentUserActionId(腾讯广告行为数据源ID)与 tencentSecretKey(加密密钥)后方可生效。

# 新手引导事件上报

在用户首次进入游戏后触发新手引导流程时上报开始,完成新手引导教程时上报完成(2.4.4 版本新增)。

注:示例代码中的参数或选项均为演示数据,仅供参考,谢谢!

// 事件ID
const eventId = "tutorial"; // 固定为tutorial,无需修改

// 事件参数
const eventParams = {};

// 必传参数
eventParams.status = "start"; // 新手引导状态,必填;取值:start(新手引导开始)、finish(新手引导完成)

// 可选参数
eventParams.extendParamJson = JSON.stringify({ accountId: 123456789, areaId: 1, roleId: 123456789 }); // 扩展参数(将透传至腾讯广告平台),可选

// 执行上报
sdkInstance.trackEvent(eventId, eventParams);

参数说明如下表所示:

字段 类型 必填 说明
status string 是

新手引导状态,新手引导开始时上报一次 start,完成时上报一次 finish

  • start - 新手引导开始
  • finish - 新手引导完成
extendParamJson string 否 扩展参数(将透传至腾讯广告平台)

注意事项

  • 事件ID eventId 固定为 tutorial,无需修改;
  • 以上事件将由SDK转发至腾讯广告平台,需在初始化时配置 tencentUserActionId(腾讯广告行为数据源ID)与 tencentSecretKey(加密密钥)后方可生效。

# 关卡事件上报

在关卡循环的各节点进行上报:进入关卡(关卡场景开始渲染第一帧)、通过关卡、关卡失败、中途退出关卡;中途退出定义:指终止了当下游戏的进程,包括局内外的游戏停止、退出等行为(2.4.4 版本新增)。

注:示例代码中的参数或选项均为演示数据,仅供参考,谢谢!

// 事件ID
const eventId = "level"; // 固定为level,无需修改

// 事件参数
const eventParams = {};

// 必传参数
eventParams.status = "enter"; // 关卡事件类型,必填;取值:enter(进入关卡)、exit(中途退出关卡)、lose(关卡失败)、pass(通过关卡)
eventParams.levelId = 1; // 关卡ID,必填

// 条件必传参数
eventParams.adCount = 1; // 关卡内广告互动次数(注意,此处指在关卡内广告观看完成的次数),status 为 exit、lose、pass 时必填;按照最小循环关卡计数

// 有则必报参数
eventParams.gameMode = "简单模式"; // 游戏模式(名称),文本,如:简单模式、困难模式、特殊模式;也支持广告主自行文本上报
eventParams.chapterId = 1; // 章节ID
eventParams.levelProgress = 0.55; // 进入的关卡进度(0~1之间的数值),需保留两位小数
eventParams.duration = 60; // 关卡时长(秒);按照最小循环关卡计数
eventParams.items = ["{item_type:1,item_num:2}", "{item_type:2,item_num:2}"]; // 使用道具信息,包括道具类型和使用数量,按照最小循环关卡计数;数组格式
eventParams.roleLevel = 1; // 角色等级
eventParams.roleStamina = 10; // 角色体力
eventParams.roleBalance = 100; // 角色金币余额

// 执行上报
sdkInstance.trackEvent(eventId, eventParams);

参数说明如下表所示:

字段 类型 必填 说明
status string 是

关卡事件类型

  • enter - 进入关卡
  • exit - 中途退出关卡
  • lose - 关卡失败
  • pass - 通过关卡
levelId string | number 是 关卡ID
adCount number 条件必填 关卡内广告互动次数(注意,此处指在关卡内广告观看完成的次数),status 为 exit、lose、pass 时必填;按照最小循环关卡计数
gameMode string 有则必报 游戏模式(名称),文本;如:简单模式、困难模式、特殊模式,也支持自定义文本上报
chapterId string | number 有则必报 章节ID
levelProgress number 有则必报 进入的关卡进度(0~1之间的数值),需保留两位小数
duration number 有则必报 关卡时长(秒);按照最小循环关卡计数
items string[] 有则必报 使用道具信息,包括道具类型和使用数量,按照最小循环关卡计数;数组格式
roleLevel number 有则必报 角色等级
roleStamina number 有则必报 角色体力
roleBalance number 有则必报 角色金币余额

注意事项

  • 事件ID eventId 固定为 level,无需修改;
  • 按腾讯官方口径,adCount、duration、items 需按照“最小循环关卡”计数:用户进入关卡后,每上报一次【进入关卡】后,经历【中途退出关卡】【关卡失败】【通过关卡】任意一个事件,即为一个循环;
  • 以上事件将由SDK转发至腾讯广告平台,需在初始化时配置 tencentUserActionId(腾讯广告行为数据源ID)与 tencentSecretKey(加密密钥)后方可生效。

# 广告事件上报

在激励视频广告位出现(点位在界面中渲染完成)与被点击(玩家点击激励视频广告位的按钮)时上报(2.4.4 版本新增)。

注:示例代码中的参数或选项均为演示数据,仅供参考,谢谢!

// 事件ID
const eventId = "ad"; // 固定为ad,无需修改

// 事件参数
const eventParams = {};

// 必传参数
eventParams.status = "appear"; // 广告事件类型,必填;取值:appear(广告位展示)、click(广告位点击)
eventParams.adPosition = 1; // 广告展示位置,必填;激励视频广告位枚举,如 1 代表复活、2 代表体力,枚举值见下方表格所示

// 执行上报
sdkInstance.trackEvent(eventId, eventParams);

参数说明如下表所示:

字段 类型 必填 说明
status string 是

广告事件类型

  • appear - 广告位展示:激励点位在界面中渲染完成
  • click - 广告位点击:玩家点击激励视频广告位的按钮
adPosition string | number 是 广告展示位置;激励视频广告位枚举,如 1 代表复活、2 代表体力,枚举值见下方表格所示

广告位枚举值(长期更新):

枚举值 广告位名称 备注
1 复活
2 体力
3 等级
4 金币
5 加时
6 钻石
7 补签到
8 宝箱
9 加速行动 疾跑
10 多倍领取
11 免广告卡
12 离线收益
13 获得礼包
14 转盘抽奖
15 宠物
16 重玩
17 撤回
18 交换
19 移动
20 吸附
21 炸弹
22 更换
23 称号
24 更多玩法
25 刷新
26 生成空瓶
27 提示
28 获取答案
29 移除
30 洗牌 打乱
31 翻转 翻牌
32 重置 刷新
33 升级收益
34 探测
35 跳过
36 每日限购
37 加筒
38 加孔位
39 加车位
40 冻结时间
41 自动点击
42 主题
43 指定消除
44 全部消除
45 随机消除 磁铁、吸钉器、清毛器、凑齐、锤子
46 排序
47 去除遮挡 遮罩、锅盖、冰块冻结
48 透明
49 缩短
50 合成
51 全屏攻击
52 剪断绳子
53 无敌
54 万能盒子
55 万能螺丝
56 解锁剧情
57 解锁章节
58 解锁关卡
59 解锁音乐
60 解锁动作
61 解锁炮台
62 解锁角色
63 解锁空位
64 解锁地图
65 解锁盒子
66 解锁装修图纸
67 解锁皮肤
68 其他

注意事项

  • 事件ID eventId 固定为 ad,无需修改;
  • 广告曝光与广告播放结束由SDK自动上报:广告展示成功渲染上屏时上报曝光,激励视频完整播放完毕时上报播放结束,游戏无需调用。
  • 以上事件将由SDK转发至腾讯广告平台,需在初始化时配置 tencentUserActionId(腾讯广告行为数据源ID)与 tencentSecretKey(加密密钥)后方可生效。

# 自定义事件上报

上报其他自定义事件;自定义事件的名称、参数无固定格式,请结合游戏业务需要或运营需求自行上报。

注:示例代码中的参数或选项均为演示数据,仅供参考,谢谢!

// 事件ID
const eventId = "custom"; // 固定为custom,无需修改

// 事件参数
const eventParams = {};

// 必传参数
eventParams.eventName = "play"; // 自定义事件名称,必填;如这里的 play 代表立即试玩事件
eventParams.extendParamJson = JSON.stringify({ accountId: 123456789, level: 10, vip: 3 }); // 扩展参数,必填;格式为JSON字符串,包含自定义属性键值对,若无自定义属性可传空对象 JSON.stringify({})

// 可选参数
eventParams.eventObj = "btn_play"; // 事件操作对象,如果是按钮点击事件,则对应按钮ID,如 btn_play
eventParams.eventCode = "play"; // 事件操作原因,如 play
eventParams.eventResult = "game_lobby"; // 事件操作结果,如果是按钮点击事件,则返回按钮点击的结果,例如跳转至另一个页面,则填写结果页ID,如 game_lobby
eventParams.areaId = "1001"; // 游戏大区ID,若游戏无大区概念,可不填,默认值为 1,表示初始大区编号
eventParams.roleId = "123456"; // 角色ID,若游戏无角色概念,可不填,默认值同 accountId 账号ID

// 执行上报
sdkInstance.trackEvent(eventId, eventParams);

注意事项

  • 事件ID eventId 固定为 custom,无需修改;
  • 事件参数 eventParams 必须包含 eventName、extendParamJson 字段。
Last Updated: 2026/10/29 14:22:42