腾讯广告小游戏 SDK 集成

引力引擎 SDK 支持将数据同步上报给腾讯广告小游戏 SDK，方便开发者以较低的接入成本完成腾讯 SDK 适配。本文档讲解 Unity 项目发布到 微信小游戏 平台后的配置与埋点调用方式，与 小游戏 SDK 版本的区别在于：Unity 版本需要您自行引入 dn-sdk 并完成初始化。

1. 更新记录

2. 接入步骤总览

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

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

3. 按照Unity SDK 快速集成文档完成配置并启动 SDK、用户初始化。

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

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

3. 添加腾讯 SDK 上报宏参数

需要在 Unity 打包配置中添加宏参数 ENABLE_TENCENT_SDK_TRACK，添加步骤如下：

1. 打开 Unity 的 Project Settings 界面。

2. 找到 Scripting Define Symbols，新增一行输入 ENABLE_TENCENT_SDK_TRACK，然后点击 Apply 按钮完成设置。

4. 上报失败日志收集宏参数（5.0.38 及以上版本支持，可选）

如需收集腾讯上报失败日志，可配置宏参数 ENABLE_TENCENT_SDK_TRACK_ERROR，添加步骤如下：

1. 打开 Unity 的 Project Settings 界面。

2. 找到 Scripting Define Symbols，新增一行输入 ENABLE_TENCENT_SDK_TRACK_ERROR，然后点击 Apply 按钮完成设置。

3. 在引力后台 应用管理 页面同步应用的数据版本到 1048，此时应用元事件中会新增 $TencentSDKLog，引力 SDK 将在腾讯 SDK 上报失败时上报此事件。

$TencentSDKLog 事件含有错误码、错误信息、追溯 ID 等属性，均由腾讯返回，可在用户细查（搜索 Client ID 后点击「深度挖掘」，筛选「腾讯SDK上报日志事件」）或事件分析（批量查看上报失败的用户及错误信息）中查看。

5. 小游戏激励直玩能力改造

官方参考文档：腾讯广告-小游戏激励直玩能力文档

5.1 添加直玩状态判断宏参数（5.0.38 及以上版本支持，可选）

需要在 Unity 打包配置中添加宏参数 ENABLE_AUTO_CHECK_DIRECT_AD_GAME_STATUS：

1. 打开 Unity 的 Project Settings 界面。

2. 找到 Scripting Define Symbols，新增一行输入 ENABLE_AUTO_CHECK_DIRECT_AD_GAME_STATUS，然后点击 Apply 按钮完成设置。

6. 确保传入的 clientId 为微信 openid

由于腾讯 SDK 要求启动之后立即调用 setOpenId 方法上报 openid，故您在调用 StartGravityEngine 启动引力 SDK 时，传入的 clientId 请务必为小游戏的 openid，否则可能会导致数据异常。

7. 配置用户沉默唤起周期

在启动引力引擎 SDK 前，先调用 SetSilentPeriod 方法配置用户沉默唤起周期长度：

// 配置沉默唤起周期长度为30，腾讯常见回流周期：7、14、30，请根据产品实际需求配置，默认为30
GravityHelper.SetSilentPeriod(30);
// 历史用户回传"注册"事件的有效时间范围。决定回传多久前发生的用户注册行为，默认值为 7
GravityHelper.SetRegisterDelayDay(7);
// 然后再启动引力引擎SDK
GravityEngineAPI.StartGravityEngine(accessToken, clientId, GravityEngineAPI.SDKRunMode.NORMAL);

如果未配置沉默唤起周期，则默认为 30 天。

8. 添加腾讯安全域名

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

9. 完善埋点配置

针对调用时机明确的埋点事件，如 首次注册（REGISTER） 和 沉默唤醒（RE_ACTIVE） 事件，引力已在 SDK 内部自动采集上报。

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

9.1 付费（Purchase/Pay）

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

9.1.1 付费事件回传

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

// 仅上报付费事件到引力后端
// payAmount：付费金额，单位为分；payType：付费类型，例如 CNY、USD
// orderId：订单号；payReason：付费原因；payMethod：付费方式
GravityEngineAPI.TrackPayEvent(300, "CNY", "your_order_id", "月卡", "支付宝");

// 仅上报付费事件到腾讯SDK，payAmount：付费金额，单位为分
GravityEngineAPI.TrackPayEventToTencent(300);

以上两个方法可以灵活搭配调用：

• 需要同时回传给引力和腾讯：先调用 TrackPayEvent，再调用 TrackPayEventToTencent。

• 只需要回传给腾讯：一般是之前通过 API 方式上报引力，可使用本模式补齐对腾讯的上报，只调用 TrackPayEventToTencent。

• 只需要回传给引力：只调用 TrackPayEvent。

9.2 收藏小游戏（AddToWishList）

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

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

9.3 分享小游戏（Share）

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

// shareType 分享类型：APP_MESSAGE / TIME_LINE
// 转发给朋友
GravityEngineAPI.TrackMPShare("APP_MESSAGE");
// 分享到朋友圈
GravityEngineAPI.TrackMPShare("TIME_LINE");

9.4 创建角色（CreateRole）（IAP/混变）

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

// roleName 角色名
GravityEngineAPI.TrackMPCreateRole("法师");

9.5 完成新手引导（TutorialFinish）

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

GravityEngineAPI.TrackMPTutorialFinish();

9.6 游戏等级提升（UpdateLevel）（IAP/混变）

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

// level 游戏等级；power 游戏能量
GravityEngineAPI.TrackMPUpdateLevel(100, 1000);

9.7 浏览商城页面（ViewMallContent）（IAP/混变）

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

GravityEngineAPI.TrackMPViewMallContent();

9.8 浏览游戏活动页面（ViewActivityContent）（IAP/混变）

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

GravityEngineAPI.TrackMPViewActivityContent();

9.9 DN SDK 初始化 TrackMPAppStart（5.0.37 及以上版本支持）

腾讯 SDK 初始化成功后立即调用。此事件仅发送至腾讯分析后台，不会同步至引力平台。

GravityEngineAPI.TrackMPAppStart();

9.10 加载完成 TrackMPLoadFinish（5.0.37 及以上版本支持）（IAA）

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

GravityEngineAPI.TrackMPLoadFinish();

9.11 用户订阅 TrackMPSubscribe（5.0.37 及以上版本支持）（IAA）

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

GravityEngineAPI.TrackMPSubscribe();

9.12 开始新手引导 TrackMPTutorialStart（5.0.37 及以上版本支持）（IAA）

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

GravityEngineAPI.TrackMPTutorialStart();

9.13 进入关卡 TrackMPLevelEnter（5.0.37 及以上版本支持）（IAA）

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

// level_id 进入的关卡ID；enter_level_name 游戏关卡名称；game_mode 游戏模式（名称）
// enter_level_id 进入的关卡进度（0-1之间，保留两位小数）；coin_amount 金币数
// stamina_value 体力值；level_value 等级值
GravityEngineAPI.TrackMPLevelEnter(1, "关卡1", "简单模式", 0.2, 1, 1, 1);

9.14 中途退出关卡 TrackMPLevelExit（5.0.37 及以上版本支持）（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 等级值
GravityEngineAPI.TrackMPLevelExit(1, 2, [], "简单模式", 0.2, 10, 1, 1, 1, 1);

9.15 关卡失败 TrackMPLevelFail（5.0.37 及以上版本支持）（IAA）

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

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

9.16 关卡成功 TrackMPLevelPass（5.0.37 及以上版本支持）（IAA）

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

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

9.17 广告位展示 TrackMPAdPlacementShow（5.0.37 及以上版本支持）（IAA）

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

// ad_placement_type 广告位类型，枚举见腾讯官方文档
GravityEngineAPI.TrackMPAdPlacementShow(1);

9.18 广告位点击 TrackMPAdPlacementClick（5.0.37 及以上版本支持）（IAA）

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

GravityEngineAPI.TrackMPAdPlacementClick(1);

9.19 广告位广告展示 TrackMPAdPlacementVideoShow（5.0.37 及以上版本支持）（IAA）

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

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

9.20 广告展示完成 TrackMPAdPlacementVideoFinish（5.0.37 及以上版本支持）（IAA）

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

GravityEngineAPI.TrackMPAdPlacementVideoFinish(1);

9.21 自定义事件 TrackMPEvent（5.0.37 及以上版本支持）

如需上报其他微信事件，请根据腾讯文档在对应时机上报对应事件：腾讯广告-IAA微信小游戏采集行为列表。

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

10. 编译并引入 dn-sdk

10.1 将 Unity 项目编译成小游戏项目

使用微信小游戏转化工具或其他工具将 Unity 项目编译成小游戏项目，得到 game.js 文件。

10.2 修改 game.js 引入 dn-sdk 并完成初始化

1. 下载 dn-sdk 文件，将其导入到 game.js 同级目录，并按照上图所示操作引入当前文件到 game.js 中。

   dn-sdk 请从腾讯官方文档提供的下载地址获取。

2. 调用腾讯小游戏 SDK 的初始化方法，传入腾讯侧参数：

import { SDK } from "./dn-sdk-minigame-1.5.11.js";

try {
  // 初始化
  GameGlobal.dnSDK = new SDK({
    user_action_set_id: 123xxxxxx,
    secret_key: "xxxxxxxxxxxxxxxxxxx",
    appid: "xxxxxxxxxxxxx",
  });
} catch {}

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

11. 常见问题自查

• 数据未上报腾讯：

  • 检查 clientId 是否为微信 openid。

  • 检查宏定义 ENABLE_TENCENT_SDK_TRACK 是否配置。

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

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

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

  • 腾讯小游戏广告 SDK CHECKLIST：腾讯小游戏广告 SDK CHECKLIST

  • 腾讯 DN 数据校验未通过自查文档：DN 数据校验自查

更多常见问题请参考引力微小 SDK 常见 Q&A。