腾讯广告小游戏 SDK 集成
介绍引力引擎小游戏 SDK 内置的腾讯广告小游戏 SDK 接入方式,包含 config 配置、腾讯安全域名、埋点事件调用与常见问题自查。
引力引擎 SDK 内置了腾讯广告小游戏 SDK,方便开发者以较低的接入成本完成腾讯 SDK 适配。本文档讲解接入过程中的配置与埋点调用方式。本文档适用于 微信小游戏 平台。
引力 SDK 的这次改造仅是为了方便客户快速支持腾讯小游戏 SDK,并非必须使用引力 SDK 上报给腾讯,您依然可以直接与腾讯 SDK 对接,参考腾讯 SDK 官方文档。
1. 更新记录
| 更新日期 | 更新内容 |
|---|---|
| 2026-09-10 | 6.0.13 及以上版本,腾讯广告小游戏 SDK 由 1.5.7 更新至 1.5.11 |
| 2026-09-04 | 补全事件类型说明,新增 IAA、IAP/混变标识,未标注类型的事件为双报 |
| 2026-07-28 | 6.0.11 及以上版本 silentPeriod 默认值由 7 天调整为 30 天 |
2. 接入步骤总览
-
升级引力引擎 SDK 到 5.0.8 及以上版本。
-
在引力后台 应用管理 页面同步数据版本到 1052 及以上。
-
按照微信小游戏快速集成文档完成 SDK 启动与用户初始化。
-
验证数据上报到引力后台的通路是否正常。
-
改造部分代码,完成腾讯 SDK 埋点采集,详见下文。
3. 配置 tencentSdkData
const config = {
accessToken: "your_access_token",
clientId: "your_openid", // 如果当前还无法获取,可以不传但不能传空字符串,后续通过 setupAndStart 设置
openId: "your_openid",
name: "ge",
tencentSdkData: {
// 数据源ID,数字,必填
user_action_set_id: "your_user_action_set_id",
// 加密key,必填
secret_key: "your_secret_key",
// 微信小游戏APPID,wx开头,必填
appid: "wx123xyz123xyz123x",
// 沉默唤起周期长度,腾讯常见回流周期:7、14、30,选填,默认为30
silentPeriod: 30,
// 历史用户回传"注册"事件的有效时间范围,默认值为 7
registerDelayDay: 7,
// 腾讯SDK debug开关,默认为false
enableDebug: false,
},
};3.1 参数说明
| 参数名 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| user_action_set_id | number | 是 | 数据源 ID |
| secret_key | string | 是 | 加密 key |
| appid | string | 是 | 微信小游戏 APPID,wx 开头 |
| silentPeriod | number | 否 | 沉默唤起周期长度,腾讯常见回流周期为 7、14、30,默认为 30 |
| registerDelayDay | number | 否 | 历史用户回传「注册」事件的有效时间范围,默认值为 7 |
| enableDebug | boolean | 否 | 腾讯 SDK debug 开关,默认为 false |
| enableLogTrack | boolean | 否 | 是否采集腾讯上报失败日志到引力,默认 false |
| onReportFail | function | 否 | 腾讯 SDK 上报失败回调函数 |
| onReportComplete | function | 否 | 腾讯 SDK 上报完成回调函数 |
如果不需要使用腾讯 SDK 回传,请不要添加 tencentSdkData 参数。
4. 添加腾讯安全域名
为了腾讯 SDK 数据正常回传,您需要在微信小游戏后台将 https://api.datanexus.qq.com 添加到安全域名中。


5. 优化调用时机
引力 SDK 启动配置总共分为三个步骤,调用时机可以进一步优化如下。
5.1 初始化 GravityEngine 实例对象
建议在应用启动之后立即调用,如调用时还无法获取 openid,可以不传 clientId 参数(不要传空字符串),后续获取到 openid 之后通过 setupAndStart 补齐。
每次冷启动过程中,GravityEngine 的实例化方法 new GravityEngine() 与初始化方法 setupAndStart() 均只能被调用一次,clientId 参数必须在这两个方法的其中一个传入。
const ge = new GravityEngine(config);5.2 开启上报失败日志埋点
在引力后台 应用管理 页面同步应用的数据版本到 1048,此时应用元事件中会新增 $TencentSDKLog,引力 SDK 将在腾讯 SDK 上报失败时上报该事件。


需要在初始化引力 SDK 时额外传入 enableLogTrack 才会开启采集,默认关闭:
const config = {
// 其他配置同上
tencentSdkData: {
// 配置是否开启腾讯上报事件失败日志埋点采集到引力功能,默认为 false
enableLogTrack: true,
},
};$TencentSDKLog 事件含有错误码、错误信息、追溯 ID 等属性,均由腾讯返回,您可在以下两个功能中获取具体信息并转发给腾讯配合查询:



-
用户细查:当能定位到具体上报失败的用户时,可以搜索具体的 Client ID,点击「深度挖掘」,筛选「腾讯SDK上报日志事件」。
-
事件分析:批量查看上报失败的用户以及对应的错误信息。
5.3 开启腾讯 SDK 上报回调
const config = {
// 其他配置同上
tencentSdkData: {
// 腾讯SDK上报失败回调函数
onReportFail: onReportFail,
// 腾讯SDK上报完成回调函数
onReportComplete: onReportComplete,
},
};5.4 开启付费上报订单 ID 去重
初始化引力 SDK 时额外传入 enableOrderDeduplication 才会开启,默认关闭。开启之后通过腾讯 SDK 上报付费事件时会携带 outer_action_id 参数,传值为订单 ID。
const config = {
// 其他配置同上
tencentSdkData: {
// 配置是否开启腾讯sdk付费事件上报通过订单 Id 去重功能,默认为 false
enableOrderDeduplication: true,
},
};5.5 启动 SDK 引擎
建议在获取到 openid 之后调用 setupAndStart,如果上一步没有把 openid 当做 clientId 传入,本步骤仍可传入:
ge.setupAndStart({ clientId: "your_openid", openId: "your_openid" });如果您升级引力 SDK 之前传入的 clientId 不是小游戏的 openid,请确保:
-
clientId:请继续保持原来的 ID 回传,即原来不是 openid,现在还不是openid! -
openId:请确保传入真实有效的openid,否则会影响腾讯广告的归因判定,非常重要!
5.6 调用用户初始化接口
ge.initialize({
name: "your_name",
version: 123,
enable_sync_attribution: false,
})
.then((res) => {
console.log("initialize success ", res);
})
.catch((err) => {
console.log("initialize failed, error is ", err);
});6. 小游戏激励直玩能力改造
官方参考文档:腾讯广告-小游戏激励直玩能力文档
注意:必须使用 6.0.8 及以上版本的 SDK 才可使用。
6.1 开启腾讯 SDK 直玩状态判断(可选)
const config = {
accessToken: "your_access_token",
clientId: "your_openid",
openId: "your_openid",
name: "ge",
// 腾讯SDK 直玩状态判断,默认为false,true为开启微信小游戏直玩蒙层判断
autoCheckDirectAdGameStatus: true,
};
const ge = new GravityEngine(config);7. 完善埋点配置
针对调用时机明确的埋点事件,如 小游戏启动(START_APP)、首次注册(REGISTER) 和 沉默唤醒(RE_ACTIVE) 事件,引力已在 SDK 内部自动采集上报。
如果初始化时未传入 silentPeriod 参数配置沉默唤起周期,则默认为 30 天。

其他事件需要您手动触发,在合适的时机调用引力 SDK 提供的快捷方法,可以同时上报关键事件给引力后台和腾讯 SDK。下文标注了 IAA、IAP/混变的事件仅对对应变现类型生效,未标注类型的事件为双报。
7.1 付费(Purchase/Pay)
针对付费事件是否需要全量回传,引力提供了两种模式供您选择。
7.1.1 付费事件回传
即在触发付费事件时全部回传到腾讯 SDK,不需要通过引力映射系统判定是否回传,则使用本模式。
// 仅上报付费事件到引力后端
// payAmount:付费金额,单位为分;payType:货币类型;orderId:订单号
// payReason:付费原因,例如购买钻石、办理月卡;payMethod:付费方式
ge.payEvent(300, "CNY", "your_order_id", "月卡", "支付宝");
// 仅上报付费事件到腾讯SDK
// payAmount:付费金额,单位为分;orderId:订单号(需开启enableOrderDeduplication)
ge.payEventToTencent(300);以上两个方法可以灵活搭配调用:
-
需要同时回传给引力和腾讯:先调用
payEventToTencent,再调用payEvent。 -
只需要回传给腾讯:一般是之前通过 API 方式上报引力,可以使用本模式补齐对腾讯的上报,只调用
payEventToTencent。 -
只需要回传给引力:只调用
payEvent。
7.2 收藏小游戏(AddToWishList)
在用户收藏小游戏时上报,包括收藏、添加到我的小程序、添加到桌面以及小游戏自定义的收藏逻辑。
// wishType 枚举值:普通收藏(default)/添加到我的小程序(my)/添加到桌面(desktop)/其他(others)
ge.onAddToWishListEvent("default");
// 举例如下
wx.onAddToFavorites(() => {
ge.onAddToWishListEvent("default");
});7.3 分享小游戏(Share)
在用户分享小游戏时上报,需区分是【转发给朋友】还是【分享到朋友圈】。
// shareType 枚举:转发给朋友(APP_MESSAGE)/分享到朋友圈(TIME_LINE)
ge.onShareEvent("APP_MESSAGE");
// 转发给朋友
wx.onShareAppMessage(() => {
ge.onShareEvent("APP_MESSAGE");
});
// 分享到朋友圈
wx.onShareTimeline(() => {
ge.onShareEvent("TIME_LINE");
});7.4 创建角色(CreateRole)(IAP/混变)
在触发创角事件时全部回传到腾讯 SDK,不需要通过引力映射系统判定是否回传。用户在小游戏内创建角色成功后上报 CREATE_ROLE 行为,可添加角色名等自定义参数。
// role_name 角色名
ge.onCreateRoleEvent("法师");7.5 完成新手引导(TutorialFinish)
在触发完成新手引导事件时全部回传到腾讯 SDK。用户完成新手指引教程或者完成教程关卡后上报 TUTORIAL_FINISH 行为。
ge.onTutorialFinishEvent();7.6 游戏等级提升(UpdateLevel)(IAP/混变)
用户完成游戏等级提升时上报 UPDATE_LEVEL 行为,可添加当前游戏等级、游戏能量等自定义参数。
// userLevel 游戏等级;userPower 游戏能量
ge.onUpdateLevelEvent(100, 10);7.7 浏览商城页面(ViewMallContent)(IAP/混变)
用户浏览商城页面时上报。
ge.onViewMallContentEvent();7.8 浏览游戏活动页面(ViewActivityContent)(IAP/混变)
用户浏览活动页面时上报。
ge.onViewActivityContentEvent();7.9 加载完成 TrackMPLoadFinish(6.0.6 及以上版本支持)(IAA)
loading 页面完成,进入游戏第一帧时上报。
ge.TrackMPLoadFinish();7.10 用户订阅 TrackMPSubscribe(6.0.6 及以上版本支持)(IAA)
玩家完成订阅操作(勾选订阅协议并点击确认),系统返回订阅成功结果时上报。
ge.TrackMPSubscribe();7.11 开始新手引导 TrackMPTutorialStart(6.0.6 及以上版本支持)(IAA)
玩家首次进入游戏后,触发游戏第 1 关新手引导流程时上报。为规范数据统计口径,本事件中的「新手引导」唯一对应游戏第 1 关,所有新手引导流程均内嵌于第 1 关。
ge.TrackMPTutorialStart();7.12 进入关卡 TrackMPLevelEnter(6.0.6 及以上版本支持)(IAA)
主玩法关卡场景开始渲染第一帧时上报。
// level_id 进入的关卡ID;enter_level_name 游戏关卡名称;game_mode 游戏模式(名称)
// enter_level_id 进入的关卡进度(0-1之间,保留两位小数);coin_amount 金币数
// stamina_value 体力值;level_value 等级值
ge.TrackMPLevelEnter(1, "关卡1", "简单模式", 0.2, 1, 1, 1, 1);7.13 退出关卡 TrackMPLevelExit(6.0.6 及以上版本支持)(IAA)
中途退出关卡时上报。中途退出定义:指终止了当下游戏的进程,包括局内外的游戏停止、退出等行为。
// level_id 关卡ID;ad_cnt 关卡中点击、完成广告观看的次数;items 使用道具信息
// 例:["{item_type:4,item_num:3}","{item_type:22,item_num:2}"]
// game_mode 游戏模式;enter_level_id 关卡进度;duration 用户时长;chapter_id 章节ID
// coin_amount 金币数;stamina_value 体力值;level_value 等级值
ge.TrackMPLevelExit(1, 2, [], "简单模式", 0.2, 10, 1, 1, 1, 1);7.14 关卡失败 TrackMPLevelFail(6.0.6 及以上版本支持)(IAA)
关卡失败时上报,参数同退出关卡 TrackMPLevelExit。
ge.TrackMPLevelFail(1, 2, [], "简单模式", 0.2, 10, 1, 1, 1, 1);7.15 关卡成功 TrackMPLevelPass(6.0.6 及以上版本支持)(IAA)
关卡通关时上报,参数同退出关卡 TrackMPLevelExit。
ge.TrackMPLevelPass(1, 2, [], "简单模式", 0.2, 10, 1, 1, 1, 1);7.16 广告位展示 TrackMPAdPlacementShow(6.0.6 及以上版本支持)(IAA)
激励点位出现(激励视频点位在界面中渲染完成)时上报。
// ad_placement_type 激励视频广告行为事件,枚举见腾讯官方文档
ge.TrackMPAdPlacementShow(1);7.17 广告位点击 TrackMPAdPlacementClick(6.0.6 及以上版本支持)(IAA)
玩家点击激励视频广告位的具体按钮时上报,参数同广告位展示。
ge.TrackMPAdPlacementClick(1);7.18 广告位广告展示 TrackMPAdPlacementVideoShow(6.0.6 及以上版本支持)(IAA)
广告位产生曝光(插屏、横幅等非激励广告在界面中渲染完成,玩家可见)时上报。
// ad_type 广告位类型:1-激励视频,2-插屏,3-格子,4-banner
ge.TrackMPAdPlacementVideoShow(1);7.19 广告展示完成 TrackMPAdPlacementVideoFinish(6.0.6 及以上版本支持)(IAA)
激励视频完整播放完毕、显示「获得奖励」提示时上报,参数同广告位展示。
ge.TrackMPAdPlacementVideoFinish(1);7.20 自定义事件 TrackMPEvent(6.0.6 及以上版本支持)
如需上报其他微信事件,请根据腾讯文档在对应时机上报对应事件:腾讯广告-IAA微信小游戏采集行为列表。
请注意
通过此方式上报的数据将仅发送至腾讯分析后台,不会同步至引力平台,相关数据请在腾讯侧的分析后台查看。
// 示例:上报用户主题点击
ge.TrackMPEvent("THEME_CLICK");7.21 调用腾讯 SDK 原生接口
对于引力 SDK 未提供封装的方法,您可以直接调用底层 SDK 的原始接口。
请注意
通过此方式上报的数据将仅发送至腾讯分析后台,不会同步至引力平台,相关数据请在腾讯侧的分析后台查看。
请根据您的项目开发模式,使用对应的调用路径:
-
原生/混生开发:直接通过引力桥接的 SDK 实例调用,格式为
ge.sdk.xxx。 -
纯引擎开发(如使用 Cocos Creator 等引擎):通过引力封装的 JavaScript 桥接层调用,格式为
ge.geJs.sdk.xxx。
其中 xxx 为您需要调用的腾讯 SDK 具体方法名(例如 track),具体可用方法请参考腾讯侧 SDK 官方文档。
至此已完成引力 SDK 与腾讯小游戏 SDK 的集成。
8. 常见问题自查
-
数据未上报腾讯:
-
检查
clientId/openId是否为微信 openid。 -
检查腾讯 SDK 初始化参数是否正确。
-
检查微信后台配置的合法域名是否含有腾讯安全域名:
https://api.datanexus.qq.com。 -
检查是否有调用回传腾讯的相关方法。
-
腾讯小游戏广告 SDK CHECKLIST:腾讯小游戏广告 SDK CHECKLIST
-
腾讯 DN 数据校验未通过自查文档:DN 数据校验自查
-
更多常见问题请参考引力微小 SDK 常见 Q&A。