跳到主要内容
当前模块客户端 SDK 集成
AI-ready documentation

腾讯广告小游戏 SDK 集成

介绍引力引擎小游戏 SDK 内置的腾讯广告小游戏 SDK 接入方式,包含 config 配置、腾讯安全域名、埋点事件调用与常见问题自查。

查看 Markdown

引力引擎 SDK 内置了腾讯广告小游戏 SDK,方便开发者以较低的接入成本完成腾讯 SDK 适配。本文档讲解接入过程中的配置与埋点调用方式。本文档适用于 微信小游戏 平台。

引力 SDK 的这次改造仅是为了方便客户快速支持腾讯小游戏 SDK,并非必须使用引力 SDK 上报给腾讯,您依然可以直接与腾讯 SDK 对接,参考腾讯 SDK 官方文档。

1. 更新记录

更新日期更新内容
2026-09-106.0.13 及以上版本,腾讯广告小游戏 SDK 由 1.5.7 更新至 1.5.11
2026-09-04补全事件类型说明,新增 IAA、IAP/混变标识,未标注类型的事件为双报
2026-07-286.0.11 及以上版本 silentPeriod 默认值由 7 天调整为 30 天

2. 接入步骤总览

  1. 升级引力引擎 SDK 到 5.0.8 及以上版本。

  2. 在引力后台 应用管理 页面同步数据版本到 1052 及以上。

  3. 按照微信小游戏快速集成文档完成 SDK 启动与用户初始化。

  4. 验证数据上报到引力后台的通路是否正常。

  5. 改造部分代码,完成腾讯 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_idnumber是数据源 ID
secret_keystring是加密 key
appidstring是微信小游戏 APPID,wx 开头
silentPeriodnumber否沉默唤起周期长度,腾讯常见回流周期为 7、14、30,默认为 30
registerDelayDaynumber否历史用户回传「注册」事件的有效时间范围,默认值为 7
enableDebugboolean否腾讯 SDK debug 开关,默认为 false
enableLogTrackboolean否是否采集腾讯上报失败日志到引力,默认 false
onReportFailfunction否腾讯 SDK 上报失败回调函数
onReportCompletefunction否腾讯 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 等属性,均由腾讯返回,您可在以下两个功能中获取具体信息并转发给腾讯配合查询:

腾讯SDK上报日志事件属性

腾讯SDK上报日志事件详情

腾讯SDK上报日志事件列表

  • 用户细查:当能定位到具体上报失败的用户时,可以搜索具体的 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,请确保:

  1. clientId:请继续保持原来的 ID 回传,即原来不是 openid,现在还不是 openid!

  2. 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 的原始接口。

请注意

通过此方式上报的数据将仅发送至腾讯分析后台,不会同步至引力平台,相关数据请在腾讯侧的分析后台查看。

请根据您的项目开发模式,使用对应的调用路径:

  1. 原生/混生开发:直接通过引力桥接的 SDK 实例调用,格式为 ge.sdk.xxx。

  2. 纯引擎开发(如使用 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。

本页内容

1. 更新记录2. 接入步骤总览3. 配置 tencentSdkData3.1 参数说明4. 添加腾讯安全域名5. 优化调用时机5.1 初始化 GravityEngine 实例对象5.2 开启上报失败日志埋点5.3 开启腾讯 SDK 上报回调5.4 开启付费上报订单 ID 去重5.5 启动 SDK 引擎5.6 调用用户初始化接口6. 小游戏激励直玩能力改造6.1 开启腾讯 SDK 直玩状态判断(可选)7. 完善埋点配置7.1 付费(Purchase/Pay)7.1.1 付费事件回传7.2 收藏小游戏(AddToWishList)7.3 分享小游戏(Share)7.4 创建角色(CreateRole)(IAP/混变)7.5 完成新手引导(TutorialFinish)7.6 游戏等级提升(UpdateLevel)(IAP/混变)7.7 浏览商城页面(ViewMallContent)(IAP/混变)7.8 浏览游戏活动页面(ViewActivityContent)(IAP/混变)7.9 加载完成 TrackMPLoadFinish(6.0.6 及以上版本支持)(IAA)7.10 用户订阅 TrackMPSubscribe(6.0.6 及以上版本支持)(IAA)7.11 开始新手引导 TrackMPTutorialStart(6.0.6 及以上版本支持)(IAA)7.12 进入关卡 TrackMPLevelEnter(6.0.6 及以上版本支持)(IAA)7.13 退出关卡 TrackMPLevelExit(6.0.6 及以上版本支持)(IAA)7.14 关卡失败 TrackMPLevelFail(6.0.6 及以上版本支持)(IAA)7.15 关卡成功 TrackMPLevelPass(6.0.6 及以上版本支持)(IAA)7.16 广告位展示 TrackMPAdPlacementShow(6.0.6 及以上版本支持)(IAA)7.17 广告位点击 TrackMPAdPlacementClick(6.0.6 及以上版本支持)(IAA)7.18 广告位广告展示 TrackMPAdPlacementVideoShow(6.0.6 及以上版本支持)(IAA)7.19 广告展示完成 TrackMPAdPlacementVideoFinish(6.0.6 及以上版本支持)(IAA)7.20 自定义事件 TrackMPEvent(6.0.6 及以上版本支持)7.21 调用腾讯 SDK 原生接口8. 常见问题自查