# 腾讯广告小游戏 SDK 集成 > 来源：https://help.gravity-engine.com/docs/client-sdk/unity/advanced/tencent-ads-integration > 介绍 Unity SDK 接入腾讯广告小游戏 SDK 的方式，包含上报宏参数、沉默唤起周期、C# 埋点方法，以及编译产物 game.js 引入 dn-sdk 的步骤。 引力引擎 SDK 支持将数据同步上报给腾讯广告小游戏 SDK，方便开发者以较低的接入成本完成腾讯 SDK 适配。本文档讲解 Unity 项目发布到 **微信小游戏** 平台后的配置与埋点调用方式，与 [小游戏 SDK 版本](/docs/client-sdk/mini-games/advanced/tencent-ads-integration)的区别在于：Unity 版本需要您自行引入 dn-sdk 并完成初始化。 > **注意** > 引力 SDK 的这次集成改造仅是为了方便客户快速支持腾讯小游戏 SDK，并非必须使用引力 SDK 上报给腾讯，您依然可以直接与腾讯 SDK 对接，参考[腾讯 SDK 官方文档](https://doc.weixin.qq.com/doc/w3_ANYALQY-AEkzz9MDrwwS7KEbhTij7?scode=AJEAIQdfAAo2w8EWjLABgASwbKACc)。 ## 1. 更新记录 [#1-更新记录] | 更新日期 | 更新内容 | | ---------- | -------------------------------------------------------------------- | | 2026-09-04 | 补全事件类型说明，新增 IAA、IAP/混变标识，未标注类型的事件为双报 | | 2026-07-28 | 5.0.42 及以上版本 `silentPeriod` 默认值由 7 天调整为 30 天；支持设置 `registerDelayDay` | ## 2. 接入步骤总览 [#2-接入步骤总览] 1. 升级引力引擎 SDK 到 [4.8.34](https://github.com/GravityInfinite/Turbo-Unity-Demo/releases) 及以上版本。 2. 在引力后台 [应用管理](https://web.gravity-engine.com/#/manage/appmanage) 页面同步数据版本到 **1052** 及以上。 3. 按照[Unity SDK 快速集成](/docs/client-sdk/unity/quickstart)文档完成配置并启动 SDK、用户初始化。 4. 验证数据上报到引力后台的通路是否正常。 5. 改造部分代码，完成腾讯 SDK 埋点采集，详见下文。 ## 3. 添加腾讯 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 及以上版本支持，可选） [#4-上报失败日志收集宏参数5038-及以上版本支持可选] 如需收集腾讯上报失败日志，可配置宏参数 `ENABLE_TENCENT_SDK_TRACK_ERROR`，添加步骤如下： 1. 打开 Unity 的 Project Settings 界面。 2. 找到 `Scripting Define Symbols`，新增一行输入 `ENABLE_TENCENT_SDK_TRACK_ERROR`，然后点击 Apply 按钮完成设置。 3. 在引力后台 [应用管理](https://web.gravity-engine.com/#/manage/appmanage) 页面同步应用的数据版本到 **1048**，此时应用元事件中会新增 `$TencentSDKLog`，引力 SDK 将在腾讯 SDK 上报失败时上报此事件。 在引力后台同步数据版本 引力后台数据版本同步结果 `$TencentSDKLog` 事件含有错误码、错误信息、追溯 ID 等属性，均由腾讯返回，可在**用户细查**（搜索 Client ID 后点击「深度挖掘」，筛选「腾讯SDK上报日志事件」）或**事件分析**（批量查看上报失败的用户及错误信息）中查看。 ## 5. 小游戏激励直玩能力改造 [#5-小游戏激励直玩能力改造] 官方参考文档：[腾讯广告-小游戏激励直玩能力文档](https://docs.qq.com/doc/DUG9ScmRYRkxXa3hu) > **注意** > 请使用 **1.5.11 及以上版本的腾讯 SDK**（dn-sdk），可从[腾讯官方文档](https://doc.weixin.qq.com/doc/w3_ANYALQY-AEkzz9MDrwwS7KEbhTij7?scode=AJEAIQdfAAo2w8EWjLABgASwbKACc)提供的下载地址获取。 ### 5.1 添加直玩状态判断宏参数（5.0.38 及以上版本支持，可选） [#51-添加直玩状态判断宏参数5038-及以上版本支持可选] 需要在 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 [#6-确保传入的-clientid-为微信-openid] 由于腾讯 SDK 要求启动之后立即调用 `setOpenId` 方法上报 `openid`，故您在调用 `StartGravityEngine` 启动引力 SDK 时，传入的 `clientId` 请务必为小游戏的 `openid`，否则可能会导致数据异常。 ## 7. 配置用户沉默唤起周期 [#7-配置用户沉默唤起周期] 在启动引力引擎 SDK 前，先调用 `SetSilentPeriod` 方法配置用户沉默唤起周期长度： ```csharp // 配置沉默唤起周期长度为30，腾讯常见回流周期：7、14、30，请根据产品实际需求配置，默认为30 GravityHelper.SetSilentPeriod(30); // 历史用户回传"注册"事件的有效时间范围。决定回传多久前发生的用户注册行为，默认值为 7 GravityHelper.SetRegisterDelayDay(7); // 然后再启动引力引擎SDK GravityEngineAPI.StartGravityEngine(accessToken, clientId, GravityEngineAPI.SDKRunMode.NORMAL); ``` 如果未配置沉默唤起周期，则默认为 30 天。 沉默唤起周期上报流程 ## 8. 添加腾讯安全域名 [#8-添加腾讯安全域名] 为了腾讯 SDK 数据正常回传，您需要在微信小游戏后台将 `https://api.datanexus.qq.com` 添加到安全域名中。 在微信小游戏后台配置腾讯安全域名 微信小游戏后台安全域名列表示例 ## 9. 完善埋点配置 [#9-完善埋点配置] 针对调用时机明确的埋点事件，如 **首次注册（REGISTER）** 和 **沉默唤醒（RE\_ACTIVE）** 事件，引力已在 SDK 内部自动采集上报。 其他事件需要您手动触发，在合适的时机调用引力 SDK 提供的快捷方法，可以同时上报关键事件给**引力后台**和**腾讯 SDK**。下文标注了 IAA、IAP/混变的事件仅对对应变现类型生效，未标注类型的事件为双报。 ### 9.1 付费（Purchase/Pay） [#91-付费purchasepay] 针对付费事件是否需要全量回传，引力提供了两种模式供您选择。 #### 9.1.1 付费事件回传 [#911-付费事件回传] 即在触发付费事件时全部回传到腾讯 SDK，不需要通过引力映射系统判定是否回传，则使用本模式。 ```csharp // 仅上报付费事件到引力后端 // 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） [#92-收藏小游戏addtowishlist] 在用户收藏小游戏时上报，包括收藏、添加到我的小程序、添加到桌面以及小游戏自定义的收藏逻辑。 ```csharp // wishType 枚举值：普通收藏（default）/添加到我的小程序（my）/添加到桌面（desktop）/其他 GravityEngineAPI.TrackMPAddFavorites("desktop"); ``` ### 9.3 分享小游戏（Share） [#93-分享小游戏share] 在用户分享小游戏时上报，需区分是【转发给朋友】还是【分享到朋友圈】。 ```csharp // shareType 分享类型：APP_MESSAGE / TIME_LINE // 转发给朋友 GravityEngineAPI.TrackMPShare("APP_MESSAGE"); // 分享到朋友圈 GravityEngineAPI.TrackMPShare("TIME_LINE"); ``` ### 9.4 创建角色（CreateRole）（IAP/混变） [#94-创建角色createroleiap混变] 在触发创角事件时全部回传到腾讯 SDK，不需要通过引力映射系统判定是否回传。用户创建角色成功后上报 CREATE\_ROLE 行为，可添加角色名等自定义参数。 ```csharp // roleName 角色名 GravityEngineAPI.TrackMPCreateRole("法师"); ``` ### 9.5 完成新手引导（TutorialFinish） [#95-完成新手引导tutorialfinish] 在触发完成新手引导事件时全部回传到腾讯 SDK。用户完成新手指引教程或者完成教程关卡后上报 TUTORIAL\_FINISH 行为。 ```csharp GravityEngineAPI.TrackMPTutorialFinish(); ``` ### 9.6 游戏等级提升（UpdateLevel）（IAP/混变） [#96-游戏等级提升updateleveliap混变] 用户完成游戏等级提升时上报 UPDATE\_LEVEL 行为，可添加当前游戏等级、游戏能量等自定义参数。 ```csharp // level 游戏等级；power 游戏能量 GravityEngineAPI.TrackMPUpdateLevel(100, 1000); ``` ### 9.7 浏览商城页面（ViewMallContent）（IAP/混变） [#97-浏览商城页面viewmallcontentiap混变] 用户浏览商城页面时上报。 ```csharp GravityEngineAPI.TrackMPViewMallContent(); ``` ### 9.8 浏览游戏活动页面（ViewActivityContent）（IAP/混变） [#98-浏览游戏活动页面viewactivitycontentiap混变] 用户浏览活动页面时上报。 ```csharp GravityEngineAPI.TrackMPViewActivityContent(); ``` ### 9.9 DN SDK 初始化 TrackMPAppStart（5.0.37 及以上版本支持） [#99-dn-sdk-初始化-trackmpappstart5037-及以上版本支持] 腾讯 SDK 初始化成功后立即调用。此事件**仅发送至腾讯分析后台，不会同步至引力平台**。 ```csharp GravityEngineAPI.TrackMPAppStart(); ``` ### 9.10 加载完成 TrackMPLoadFinish（5.0.37 及以上版本支持）（IAA） [#910-加载完成-trackmploadfinish5037-及以上版本支持iaa] loading 页面完成，进入游戏第一帧时上报。 ```csharp GravityEngineAPI.TrackMPLoadFinish(); ``` ### 9.11 用户订阅 TrackMPSubscribe（5.0.37 及以上版本支持）（IAA） [#911-用户订阅-trackmpsubscribe5037-及以上版本支持iaa] 玩家完成订阅操作（勾选订阅协议并点击确认），系统返回订阅成功结果时上报。 ```csharp GravityEngineAPI.TrackMPSubscribe(); ``` ### 9.12 开始新手引导 TrackMPTutorialStart（5.0.37 及以上版本支持）（IAA） [#912-开始新手引导-trackmptutorialstart5037-及以上版本支持iaa] 玩家首次进入游戏后，触发游戏第 1 关新手引导流程时上报。本事件中的「新手引导」唯一对应游戏第 1 关，所有新手引导流程均内嵌于第 1 关。 ```csharp GravityEngineAPI.TrackMPTutorialStart(); ``` ### 9.13 进入关卡 TrackMPLevelEnter（5.0.37 及以上版本支持）（IAA） [#913-进入关卡-trackmplevelenter5037-及以上版本支持iaa] 主玩法关卡场景开始渲染第一帧时上报。 ```csharp // 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） [#914-中途退出关卡-trackmplevelexit5037-及以上版本支持iaa] 中途退出关卡时上报。中途退出定义：指终止了当下游戏的进程，包括局内外的游戏停止、退出等行为。 ```csharp // 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） [#915-关卡失败-trackmplevelfail5037-及以上版本支持iaa] 关卡失败时上报，参数同中途退出关卡 TrackMPLevelExit。 ```csharp GravityEngineAPI.TrackMPLevelFail(1, 2, [], "简单模式", 0.2, 10, 1, 1, 1, 1); ``` ### 9.16 关卡成功 TrackMPLevelPass（5.0.37 及以上版本支持）（IAA） [#916-关卡成功-trackmplevelpass5037-及以上版本支持iaa] 关卡通关时上报，参数同中途退出关卡 TrackMPLevelExit。 ```csharp GravityEngineAPI.TrackMPLevelPass(1, 2, [], "简单模式", 0.2, 10, 1, 1, 1, 1); ``` ### 9.17 广告位展示 TrackMPAdPlacementShow（5.0.37 及以上版本支持）（IAA） [#917-广告位展示-trackmpadplacementshow5037-及以上版本支持iaa] 激励点位出现（激励视频点位在界面中渲染完成）时上报。 ```csharp // ad_placement_type 广告位类型，枚举见腾讯官方文档 GravityEngineAPI.TrackMPAdPlacementShow(1); ``` ### 9.18 广告位点击 TrackMPAdPlacementClick（5.0.37 及以上版本支持）（IAA） [#918-广告位点击-trackmpadplacementclick5037-及以上版本支持iaa] 玩家点击激励视频广告位的具体按钮时上报，参数同广告位展示。 ```csharp GravityEngineAPI.TrackMPAdPlacementClick(1); ``` ### 9.19 广告位广告展示 TrackMPAdPlacementVideoShow（5.0.37 及以上版本支持）（IAA） [#919-广告位广告展示-trackmpadplacementvideoshow5037-及以上版本支持iaa] 广告位产生曝光（插屏、横幅等非激励广告在界面中渲染完成，玩家可见）时上报。 ```csharp // ad_type 广告位类型：1-激励视频，2-插屏，3-格子，4-banner GravityEngineAPI.TrackMPAdPlacementVideoShow(1); ``` ### 9.20 广告展示完成 TrackMPAdPlacementVideoFinish（5.0.37 及以上版本支持）（IAA） [#920-广告展示完成-trackmpadplacementvideofinish5037-及以上版本支持iaa] 激励视频完整播放完毕、显示「获得奖励」提示时上报，参数同广告位展示。 ```csharp GravityEngineAPI.TrackMPAdPlacementVideoFinish(1); ``` ### 9.21 自定义事件 TrackMPEvent（5.0.37 及以上版本支持） [#921-自定义事件-trackmpevent5037-及以上版本支持] 如需上报其他微信事件，请根据腾讯文档在对应时机上报对应事件：[腾讯广告-IAA微信小游戏采集行为列表](https://doc.weixin.qq.com/doc/w3_AE8AdwaBACcCNQJfr07c0QriMRK01?scode=AJEAIQdfAAoXXA3NYhAZMA9AbnABI)。 > **请注意** > 通过此方式上报的数据将**仅发送至腾讯分析后台，不会同步至引力平台**，相关数据请在腾讯侧的分析后台查看。 ```csharp // 示例：上报用户主题点击 GravityEngineAPI.TrackMPEvent("THEME_CLICK"); ``` ## 10. 编译并引入 dn-sdk [#10-编译并引入-dn-sdk] ### 10.1 将 Unity 项目编译成小游戏项目 [#101-将-unity-项目编译成小游戏项目] 使用微信小游戏转化工具或其他工具将 Unity 项目编译成小游戏项目，得到 `game.js` 文件。 Unity 项目编译成小游戏项目后的 game.js ### 10.2 修改 game.js 引入 dn-sdk 并完成初始化 [#102-修改-gamejs-引入-dn-sdk-并完成初始化] 在 game.js 中引入 dn-sdk 1. 下载 dn-sdk 文件，将其导入到 `game.js` 同级目录，并按照上图所示操作引入当前文件到 `game.js` 中。 dn-sdk 请从[腾讯官方文档](https://doc.weixin.qq.com/doc/w3_ANYALQY-AEkzz9MDrwwS7KEbhTij7?scode=AJEAIQdfAAo2w8EWjLABgASwbKACc)提供的下载地址获取。 2. 调用腾讯小游戏 SDK 的初始化方法，传入腾讯侧参数： ```js 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. 常见问题自查 [#11-常见问题自查] * **数据未上报腾讯**： * 检查 `clientId` 是否为微信 openid。 * 检查宏定义 `ENABLE_TENCENT_SDK_TRACK` 是否配置。 * 检查腾讯 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)。