# 数据统计
# 接口说明
用于上报并记录用户在游戏内的行为日志&事件(如:启动、登录、创角、充值等行为),方便观察数据的变化、快速定位问题的根源,以及追踪程序执行的过程等。
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 | 是 | 新手引导状态,新手引导开始时上报一次
|
| 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 | 是 | 关卡事件类型
|
| 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 | 是 | 广告事件类型
|
| 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字段。