文档中心 > API

reportScene: 游戏场景上报

更新时间：2026/05/20 访问次数：6912

功能描述

用于游戏运行阶段的自定义场景上报。包括启动阶段的重点节点，以及关键用户行为。

接入该能力时，可根据文档最后章节“功能自检”，检查是否上报成功。

注意：

1）上报不能做用户上报次数限制，可能引发数据统计错误、用户无法完成关键行为任务等问题。

2）401关键行为只能上报一种游戏行为，请与运营约定上报的关键行为类型。如：约定为通关一次为关键行为，那么只在用户通关时进行上报，不要再上报其他节点的用户行为。

示例

const SDK = my.tb.getInteractiveSDK()
SDK.reportScene({
  sceneId: 100,
  timestamp: Date.now(),
  costTime: 2000,
})

入参

参数名称	说明	类型	备注
sceneId	场景ID	string	/
costTime	耗时	number	可选
timestamp	当前时间戳	string	可选
extra	额外携带的参数	Object	可选
extra.money	付费金额	number	可选

场景示意

图1.：对应场景ID 301，游戏首帧渲染完成，用户用户看到首帧游戏画面的时间

图2：对应场景ID 302，资源开始加载，loading界面开始

图3：对应场景ID 303，资源加载完毕，此处以loading条走完，loading结束为标准

图4：对应场景ID 304，游戏可交互场景，用户可以进行交互（包括玩家可点击游戏开始键的场景）

SceneId说明

场景ID	场景名称	场景说明	接入说明
301	游戏首帧渲染	用户看到首帧游戏画面的时间，具体见上方图示	必须接入
302	资源开始加载	loading界面开始，具体见上方图示	必须接入
303	资源加载完毕	loading界面完成，具体见上方图示	必须接入
304	游戏可交互	首场景上屏，用户可交互，真实到达率，具体见上方图示	必须接入
311	用户首次打开游戏		买量游戏建议接入，自动对接广告平台
312	用户注册		买量游戏建议接入，自动对接广告平台
313	用户创建角色		买量游戏建议接入，自动对接广告平台
321	用户点击广告		iaa游戏建议接入，自动对接广告平台
322	用户付费	用户完成内购付费	iap游戏建议接入，并传入付费金额
401	用户关键活跃行为Lv1	上报用户在游戏内进行的重点活跃行为，由游戏根据玩法自定义设计：如每完成1局、每合成3次等。	必须接入，并结合具体玩法设计上报时机；典型应用场景：平台通过权益任务吸引用户进入游戏，任务的门槛会关联游戏内定义的活跃行为（如打3局获得奖励），进游戏后根据行为上报推进任务进度，并发放权益奖励。
402～409	战令游戏行为接入前需要与运营确认接入战令玩法、与运营确认行为内容	上报用户在游戏内进行的主线活跃行为，由游戏根据玩法自定义设计。每个不同的行为为一个单独的场景ID，游戏可按根据实际的战令系统设计，按需接入。如设计的战令任务中只涉及两个关键行为，则只需要上报402（对应关键行为1，如合成1次），403（对应关键行为2，如完成订单1次）。	典型应用场景：接入战令玩法后，用户进入游戏后能够看到长期的战令任务组，完成任务后可获得平台侧互动权益奖励。该任务组不会每日刷新，任务周期内都可完成，所以任务设计时优先考虑长线指引，引导用户逐步提升游戏活跃深度。任务内容上可交叉替换关键行为，如，任务一：通关3次；任务二：抽奖3次；任务三：通关5次；任务四：升级5次。那么对应游戏需要上报3个关键行为：402（通关1次），403（抽奖1次），404（升级1次）。注意：如战令任务行为与401涉及相同行为，也需要重复上报一次402，否则无法推进完成战令任务。
501	用户关键活跃行为Lv2【广告买量专用】接入前需与运营确认行为	上报用户在游戏内进行的浅度活跃行为，由游戏根据玩法自定义设计：如每击败1个敌人、每砍1次木材等。	典型应用场景：平台通过广告买量任务吸引用户进入游戏，任务的门槛会关联游戏内定义的活跃行为（如击败5个敌人获得奖励），进游戏后根据行为上报推进任务进度，并发放权益奖励。

功能自检

目前（2025年2月26日）已针对301～304添加埋点结果打印，开发者可以通过升级重装最新手淘客户端，扫描调试码在真机调试的Console面板查看埋点日志，自检是否上报成功。

FAQ

关于此文档暂时还没有FAQ

有用(0) 我要提问

开放平台

API

reportScene: 游戏场景上报

功能描述

示例

入参

场景示意

SceneId说明

功能自检

FAQ