# 腾讯广告小游戏 SDK 集成

> 来源：https://help.gravity-engine.com/docs/client-sdk/mini-games/advanced/tencent-ads-integration
> 介绍引力引擎小游戏 SDK 内置的腾讯广告小游戏 SDK 接入方式，包含 config 配置、腾讯安全域名、埋点事件调用与常见问题自查。



















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

> **注意**
> 引力 SDK 的这次改造仅是为了方便客户快速支持腾讯小游戏 SDK，并非必须使用引力 SDK 上报给腾讯，您依然可以直接与腾讯 SDK 对接，参考[腾讯 SDK 官方文档](https://doc.weixin.qq.com/doc/w3_ANYALQY-AEkzz9MDrwwS7KEbhTij7?scode=AJEAIQdfAAo2w8EWjLABgASwbKACc)。

## 1. 更新记录 [#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. 接入步骤总览 [#2-接入步骤总览]

1. 升级引力引擎 SDK 到 [5.0.8](https://github.com/GravityInfinite/mpg-demos/releases) 及以上版本。

2. 在引力后台 [应用管理](https://web.gravity-engine.com/#/manage/appmanage) 页面同步数据版本到 **1052** 及以上。

3. 按照[微信小游戏快速集成](/docs/client-sdk/mini-games/wechat-quickstart)文档完成 SDK 启动与用户初始化。

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

5. 改造部分代码，完成腾讯 SDK 埋点采集，详见下文。

## 3. 配置 tencentSdkData [#3-配置-tencentsdkdata]

```js
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 参数说明 [#31-参数说明]

| 参数名                   | 类型       | 是否必填 | 说明                                |
| --------------------- | -------- | ---- | --------------------------------- |
| 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. 添加腾讯安全域名 [#4-添加腾讯安全域名]

为了腾讯 SDK 数据正常回传，您需要在微信小游戏后台将 `https://api.datanexus.qq.com` 添加到安全域名中。

<img alt="在微信小游戏后台配置腾讯安全域名" src="__img0" />

<img alt="微信小游戏后台安全域名列表示例" src="__img1" />

## 5. 优化调用时机 [#5-优化调用时机]

引力 SDK 启动配置总共分为三个步骤，调用时机可以进一步优化如下。

### 5.1 初始化 GravityEngine 实例对象 [#51-初始化-gravityengine-实例对象]

建议在应用启动之后立即调用，如调用时还无法获取 `openid`，可以不传 `clientId` 参数（不要传空字符串），后续获取到 `openid` 之后通过 `setupAndStart` 补齐。

> **注意**
> **每次冷启动过程中，`GravityEngine` 的实例化方法 `new GravityEngine()` 与初始化方法 `setupAndStart()` 均只能被调用一次，`clientId` 参数必须在这两个方法的其中一个传入。**

```js
const ge = new GravityEngine(config);
```

### 5.2 开启上报失败日志埋点 [#52-开启上报失败日志埋点]

在引力后台 [应用管理](https://web.gravity-engine.com/#/manage/appmanage) 页面同步应用的数据版本到 **1048**，此时应用元事件中会新增 `$TencentSDKLog`，引力 SDK 将在腾讯 SDK 上报失败时上报该事件。

<img alt="在引力后台同步数据版本" src="__img2" />

<img alt="引力后台数据版本同步结果" src="__img3" />

需要在初始化引力 SDK 时额外传入 `enableLogTrack` 才会开启采集，默认关闭：

```js
const config = {
  // 其他配置同上
  tencentSdkData: {
    // 配置是否开启腾讯上报事件失败日志埋点采集到引力功能，默认为 false
    enableLogTrack: true,
  },
};
```

`$TencentSDKLog` 事件含有错误码、错误信息、追溯 ID 等属性，均由腾讯返回，您可在以下两个功能中获取具体信息并转发给腾讯配合查询：

<img alt="腾讯SDK上报日志事件属性" src="__img4" />

<img alt="腾讯SDK上报日志事件详情" src="__img5" />

<img alt="腾讯SDK上报日志事件列表" src="__img6" />

* **用户细查**：当能定位到具体上报失败的用户时，可以搜索具体的 Client ID，点击「深度挖掘」，筛选「腾讯SDK上报日志事件」。

* **事件分析**：批量查看上报失败的用户以及对应的错误信息。

### 5.3 开启腾讯 SDK 上报回调 [#53-开启腾讯-sdk-上报回调]

```js
const config = {
  // 其他配置同上
  tencentSdkData: {
    // 腾讯SDK上报失败回调函数
    onReportFail: onReportFail,
    // 腾讯SDK上报完成回调函数
    onReportComplete: onReportComplete,
  },
};
```

### 5.4 开启付费上报订单 ID 去重 [#54-开启付费上报订单-id-去重]

初始化引力 SDK 时额外传入 `enableOrderDeduplication` 才会开启，默认关闭。开启之后通过腾讯 SDK 上报付费事件时会携带 `outer_action_id` 参数，传值为订单 ID。

```js
const config = {
  // 其他配置同上
  tencentSdkData: {
    // 配置是否开启腾讯sdk付费事件上报通过订单 Id 去重功能，默认为 false
    enableOrderDeduplication: true,
  },
};
```

### 5.5 启动 SDK 引擎 [#55-启动-sdk-引擎]

建议在获取到 `openid` 之后调用 `setupAndStart`，如果上一步没有把 `openid` 当做 `clientId` 传入，本步骤仍可传入：

```js
ge.setupAndStart({ clientId: "your_openid", openId: "your_openid" });
```

如果您升级引力 SDK 之前传入的 `clientId` 不是小游戏的 openid，请确保：

1. `clientId`：请继续保持原来的 ID 回传，即原来不是 openid，现在还不是 `openid`！

2. `openId`：请确保传入真实有效的 `openid`，否则会影响腾讯广告的归因判定，非常重要！

### 5.6 调用用户初始化接口 [#56-调用用户初始化接口]

```js
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-小游戏激励直玩能力改造]

官方参考文档：[腾讯广告-小游戏激励直玩能力文档](https://docs.qq.com/doc/DUG9ScmRYRkxXa3hu)

注意：必须使用 [6.0.8](https://github.com/GravityInfinite/GravityEngine-Mini-Demo/releases) 及以上版本的 SDK 才可使用。

### 6.1 开启腾讯 SDK 直玩状态判断（可选） [#61-开启腾讯-sdk-直玩状态判断可选]

```js
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. 完善埋点配置 [#7-完善埋点配置]

针对调用时机明确的埋点事件，如 &#x2A;*小游戏启动（START\_APP）**、&#x2A;*首次注册（REGISTER）** 和 &#x2A;*沉默唤醒（RE\_ACTIVE）** 事件，引力已在 SDK 内部自动采集上报。

如果初始化时未传入 `silentPeriod` 参数配置沉默唤起周期，则默认为 30 天。

<img alt="沉默唤起周期上报流程" src="__img7" />

其他事件需要您手动触发，在合适的时机调用引力 SDK 提供的快捷方法，可以同时上报关键事件给**引力后台**和**腾讯 SDK**。下文标注了 IAA、IAP/混变的事件仅对对应变现类型生效，未标注类型的事件为双报。

### 7.1 付费（Purchase/Pay） [#71-付费purchasepay]

针对付费事件是否需要全量回传，引力提供了两种模式供您选择。

#### 7.1.1 付费事件回传 [#711-付费事件回传]

即在触发付费事件时全部回传到腾讯 SDK，不需要通过引力映射系统判定是否回传，则使用本模式。

```js
// 仅上报付费事件到引力后端
// 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） [#72-收藏小游戏addtowishlist]

在用户收藏小游戏时上报，包括收藏、添加到我的小程序、添加到桌面以及小游戏自定义的收藏逻辑。

```js
// wishType 枚举值：普通收藏（default）/添加到我的小程序（my）/添加到桌面（desktop）/其他（others）
ge.onAddToWishListEvent("default");

// 举例如下
wx.onAddToFavorites(() => {
  ge.onAddToWishListEvent("default");
});
```

### 7.3 分享小游戏（Share） [#73-分享小游戏share]

在用户分享小游戏时上报，需区分是【转发给朋友】还是【分享到朋友圈】。

```js
// 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/混变） [#74-创建角色createroleiap混变]

在触发创角事件时全部回传到腾讯 SDK，不需要通过引力映射系统判定是否回传。用户在小游戏内创建角色成功后上报 CREATE\_ROLE 行为，可添加角色名等自定义参数。

```js
// role_name 角色名
ge.onCreateRoleEvent("法师");
```

### 7.5 完成新手引导（TutorialFinish） [#75-完成新手引导tutorialfinish]

在触发完成新手引导事件时全部回传到腾讯 SDK。用户完成新手指引教程或者完成教程关卡后上报 TUTORIAL\_FINISH 行为。

```js
ge.onTutorialFinishEvent();
```

### 7.6 游戏等级提升（UpdateLevel）（IAP/混变） [#76-游戏等级提升updateleveliap混变]

用户完成游戏等级提升时上报 UPDATE\_LEVEL 行为，可添加当前游戏等级、游戏能量等自定义参数。

```js
// userLevel 游戏等级；userPower 游戏能量
ge.onUpdateLevelEvent(100, 10);
```

### 7.7 浏览商城页面（ViewMallContent）（IAP/混变） [#77-浏览商城页面viewmallcontentiap混变]

用户浏览商城页面时上报。

```js
ge.onViewMallContentEvent();
```

### 7.8 浏览游戏活动页面（ViewActivityContent）（IAP/混变） [#78-浏览游戏活动页面viewactivitycontentiap混变]

用户浏览活动页面时上报。

```js
ge.onViewActivityContentEvent();
```

### 7.9 加载完成 TrackMPLoadFinish（6.0.6 及以上版本支持）（IAA） [#79-加载完成-trackmploadfinish606-及以上版本支持iaa]

loading 页面完成，进入游戏第一帧时上报。

```js
ge.TrackMPLoadFinish();
```

### 7.10 用户订阅 TrackMPSubscribe（6.0.6 及以上版本支持）（IAA） [#710-用户订阅-trackmpsubscribe606-及以上版本支持iaa]

玩家完成订阅操作（勾选订阅协议并点击确认），系统返回订阅成功结果时上报。

```js
ge.TrackMPSubscribe();
```

### 7.11 开始新手引导 TrackMPTutorialStart（6.0.6 及以上版本支持）（IAA） [#711-开始新手引导-trackmptutorialstart606-及以上版本支持iaa]

玩家首次进入游戏后，触发游戏第 1 关新手引导流程时上报。为规范数据统计口径，本事件中的「新手引导」唯一对应游戏第 1 关，所有新手引导流程均内嵌于第 1 关。

```js
ge.TrackMPTutorialStart();
```

### 7.12 进入关卡 TrackMPLevelEnter（6.0.6 及以上版本支持）（IAA） [#712-进入关卡-trackmplevelenter606-及以上版本支持iaa]

主玩法关卡场景开始渲染第一帧时上报。

```js
// 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） [#713-退出关卡-trackmplevelexit606-及以上版本支持iaa]

中途退出关卡时上报。中途退出定义：指终止了当下游戏的进程，包括局内外的游戏停止、退出等行为。

```js
// 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） [#714-关卡失败-trackmplevelfail606-及以上版本支持iaa]

关卡失败时上报，参数同退出关卡 TrackMPLevelExit。

```js
ge.TrackMPLevelFail(1, 2, [], "简单模式", 0.2, 10, 1, 1, 1, 1);
```

### 7.15 关卡成功 TrackMPLevelPass（6.0.6 及以上版本支持）（IAA） [#715-关卡成功-trackmplevelpass606-及以上版本支持iaa]

关卡通关时上报，参数同退出关卡 TrackMPLevelExit。

```js
ge.TrackMPLevelPass(1, 2, [], "简单模式", 0.2, 10, 1, 1, 1, 1);
```

### 7.16 广告位展示 TrackMPAdPlacementShow（6.0.6 及以上版本支持）（IAA） [#716-广告位展示-trackmpadplacementshow606-及以上版本支持iaa]

激励点位出现（激励视频点位在界面中渲染完成）时上报。

```js
// ad_placement_type 激励视频广告行为事件，枚举见腾讯官方文档
ge.TrackMPAdPlacementShow(1);
```

### 7.17 广告位点击 TrackMPAdPlacementClick（6.0.6 及以上版本支持）（IAA） [#717-广告位点击-trackmpadplacementclick606-及以上版本支持iaa]

玩家点击激励视频广告位的具体按钮时上报，参数同广告位展示。

```js
ge.TrackMPAdPlacementClick(1);
```

### 7.18 广告位广告展示 TrackMPAdPlacementVideoShow（6.0.6 及以上版本支持）（IAA） [#718-广告位广告展示-trackmpadplacementvideoshow606-及以上版本支持iaa]

广告位产生曝光（插屏、横幅等非激励广告在界面中渲染完成，玩家可见）时上报。

```js
// ad_type 广告位类型：1-激励视频，2-插屏，3-格子，4-banner
ge.TrackMPAdPlacementVideoShow(1);
```

### 7.19 广告展示完成 TrackMPAdPlacementVideoFinish（6.0.6 及以上版本支持）（IAA） [#719-广告展示完成-trackmpadplacementvideofinish606-及以上版本支持iaa]

激励视频完整播放完毕、显示「获得奖励」提示时上报，参数同广告位展示。

```js
ge.TrackMPAdPlacementVideoFinish(1);
```

### 7.20 自定义事件 TrackMPEvent（6.0.6 及以上版本支持） [#720-自定义事件-trackmpevent606-及以上版本支持]

如需上报其他微信事件，请根据腾讯文档在对应时机上报对应事件：[腾讯广告-IAA微信小游戏采集行为列表](https://doc.weixin.qq.com/doc/w3_AE8AdwaBACcCNQJfr07c0QriMRK01?scode=AJEAIQdfAAoXXA3NYhAZMA9AbnABI)。

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

```js
// 示例：上报用户主题点击
ge.TrackMPEvent("THEME_CLICK");
```

### 7.21 调用腾讯 SDK 原生接口 [#721-调用腾讯-sdk-原生接口]

对于引力 SDK 未提供封装的方法，您可以直接调用底层 SDK 的原始接口。

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

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

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

2. **纯引擎开发**（如使用 Cocos Creator 等引擎）：通过引力封装的 JavaScript 桥接层调用，格式为 `ge.geJs.sdk.xxx`。

其中 `xxx` 为您需要调用的腾讯 SDK 具体方法名（例如 `track`），具体可用方法请参考[腾讯侧 SDK 官方文档](https://doc.weixin.qq.com/doc/w3_ANYALQY-AEkzz9MDrwwS7KEbhTij7?scode=AJEAIQdfAAo2w8EWjLABgASwbKACc)。

至此已完成引力 SDK 与腾讯小游戏 SDK 的集成。

## 8. 常见问题自查 [#8-常见问题自查]

* **数据未上报腾讯**：

  * 检查 `clientId` / `openId` 是否为微信 openid。

  * 检查腾讯 SDK 初始化参数是否正确。

  * 检查微信后台配置的合法域名是否含有腾讯**安全域名**：`https://api.datanexus.qq.com`。

  * 检查是否有调用回传腾讯的相关方法。

  * 腾讯小游戏广告 SDK CHECKLIST：[腾讯小游戏广告 SDK CHECKLIST](https://docs.qq.com/sheet/DVXpPakNRS1BGdFlS?tab=BB08J2\&nlc=1)

  * 腾讯 DN 数据校验未通过自查文档：[DN 数据校验自查](https://docs.qq.com/sheet/DVXpPakNRS1BGdFlS?tab=wekwp4\&nlc=1)

更多常见问题请参考[引力微小 SDK 常见 Q\&A](https://gravityengine.feishu.cn/docx/PmrddHYIooFTjZxGMSicAgjenbd)。