菜单

快速集成

本文档为Unity接入引力引擎的技术接入方案，具体 Demo 请参考GitHub开源项目，Demo 工程中可以参考 GravityEngineDemo.cs 脚本中对每一个方法的调用示例。

在开始接入前，建议您先阅读接入前准备以了解接入必备的基础概念。

Unity SDK 平台集成说明

🎯 集成策略说明：

Unity SDK 仅针对【微信小游戏】平台 集成了腾讯SDK。对于Unity项目发布至其他平台（如抖音小游戏、Android App、iOS App等），我们未集成任何媒体的SDK。

1. 微信小游戏平台 ✅

状态：已集成腾讯广告小游戏SDK
上报方式：需手动调用我们提供的方法进行事件上报
版本：自 4.8.34开始支持

📌 重要说明

引力SDK会自动上报以下三个基础事件给腾讯：

START_APP（小游戏启动）

REGISTER（用户注册）

RE_ACTIVE（沉默唤起）

除以上三个事件外，其他所有事件（如付费、自定义行为等）均需客户端手动调用我们提供的方法进行上报

点击查看详细集成文档：‍‌‌‬‍‍‬‍‬‍‌‍⁠‬‌‍⁠‌‌‌引力&腾讯广告小游戏 SDK 接入指南（Unity C#版）

2. 其他平台 ❌

(包括但不限于：抖音小游戏、OPPO小游戏、vivo小游戏、Android App、iOS App等)

状态：未集成任何媒体SDK（腾讯、巨量等均未集成）
上报方式：如需向媒体平台上报事件，请自行接入该平台的官方SDK

1. SDK 基础配置

1.1 SDK 引入

下载最新的 GravityEngine.unitypackage 资源文件，并导入资源文件到您的项目中：Assets > Import Package > Custom Package，选中您刚刚下载的文件。

微信小游戏：需要先接入微信团队开源的 Unity 转微信小游戏的插件。

抖音小游戏：需要先接入头条提供的 StarkSDK 插件。

快手小游戏：需要先接入快手提供的 SDK 插件 详情参考。

1.1.1 iOS配置（仅iOS应用需要配置）

找到 Targets，在 Build Settings 菜单的 Other linker flags 选项添加 -ObjC

切换到 Build Phases 选项卡，在 Link Binary With Libraries 栏目下添加如下依赖项：

libz.tbd
Security.framework
AdServices.framework（optional 形式引入）
SystemConfiguration.framework
libsqlite3.tbd
AppTrackingTransparency.framework（获取 idfa 需要）
AdSupport.framework（获取 idfa 需要）

以上依赖项，必须全部添加，否则会导致编译失败！

1.2 添加全局宏参数

正式接入之前，您需要针对不同的平台添加不同的全局宏参数，目前引力 Unity SDK 支持以下平台：

支持平台	宏参数	备注
微信小游戏	GRAVITY_WECHAT_GAME_MODE
抖音小游戏	GRAVITY_BYTEDANCE_GAME_MODE
抖音小游戏 TT SDK 模式	GRAVITY_BYTEDANCE_TT_GAME_MODE	如您已升级到 TT SDK，使用本模式，详情请参考抖小 SDK 官方文档
快手小游戏	GRAVITY_KUAISHOU_GAME_MODE
快手小游戏 WEBGL	GRAVITY_KUAISHOU_WEBGL_GAME_MODE
支付宝小游戏	GRAVITY_ALIPAY_GAME_MODE
美团小游戏	GRAVITY_MEITUAN_GAME_MODE
Bilibili 小游戏	GRAVITY_BILIBILI_GAME_MODE
华为快游戏	GRAVITY_HUAWEI_GAME_MODE
OPPO 快游戏	GRAVITY_OPPO_GAME_MODE	其他修改请参考这篇文档
小米快游戏	GRAVITY_XIAOMI_GAME_MODE	其他修改请参考这篇文档
Android	无需配置宏参数
iOS	无需配置宏参数

添加步骤如下：

打开 Project Settings 界面；
找到 Scripting Define Symbols，新增一行输入对应平台的全局宏参数，然后点击 Apply 按钮完成设置

请确保正式打包上线时，选中的宏参数依然正常生效，否则会影响到对应平台的事件上报，影响买量效果！

2.配置并启动 SDK

请参考以下代码来进行 SDK 的初始化，建议在能够获取到用户唯一 ID，如小游戏的openId、Android 设备的oaid、iOS 设备的IDFV时，尽早的进行初始化。

小游戏/快游戏

// 手动初始化（动态挂载 GravityEngineAPI 脚本）
new GameObject("GravityEngine", typeof(GravityEngineAPI));

// 小游戏应用示例
//设置实例参数并启动引擎，将以下三个参数修改成您应用对应的参数，参数可以在引力后台--设置--应用管理中查看
string accessToken = "your_access_token"; // 项目通行证，在：网站后台-->设置-->应用列表中找到Access Token列 复制（首次使用可能需要先新增应用）
string clientId = "your_user_id"; // 通常是某一个用户的唯一标识，如产品为小游戏，则必须填用户的的 openId

// 启动引力引擎
GravityEngineAPI.StartGravityEngine(accessToken, clientId, GravityEngineAPI.SDKRunMode.NORMAL);
// 开启自动采集（需升级到 5.0.13 版本才支持 MINI_GAME_ALL）
GravityEngineAPI.EnableAutoTrack(AUTO_TRACK_EVENTS.MINI_GAME_ALL, new Dictionary<string, object>(){});

配置项目合法域名

如果您的项目为小游戏，您需要将 https://backend.gravity-engine.com 和 https://api.gravity-engine.com 配置到后台 request 合法域名列表中。

如果您是从低版本引力 sdk 升级到高版本的，请一定记得添加https://api.gravity-engine.com域名到合法域名列表中，否则将导致事件采集失效，影响您的使用！

Android

// 手动初始化（动态挂载 GravityEngineAPI 脚本）
new GameObject("GravityEngine", typeof(GravityEngineAPI));

// Android原生应用示例
//设置实例参数并启动引擎，将以下三个参数修改成您应用对应的参数，参数可以在引力后台--设置--应用管理中查看
string accessToken = "your_access_token"; // 项目通行证，在：网站后台-->设置-->应用列表中找到Access Token列 复制（首次使用可能需要先新增应用）
string clientId = "default_placeholder"; // 固定值：default_placeholder
string channel = "xiaomi"; // 安装包渠道来源，比如xiaomi、huawei、应用宝

// 启动引力引擎
GravityEngineAPI.StartGravityEngine(accessToken, clientId, GravityEngineAPI.SDKRunMode.NORMAL, channel);

iOS

// 手动初始化（动态挂载 GravityEngineAPI 脚本）
new GameObject("GravityEngine", typeof(GravityEngineAPI));

// iOS原生应用示例
//设置实例参数并启动引擎，将以下参数修改成您应用对应的参数，参数可以在引力后台--设置--应用管理中查看
string accessToken = "your_access_token";
string clientId = "default_placeholder"; // iOS产品若采用引力自动获取 idfv 的方案，则这里传固定值default_placeholder即可；否则传入您自定义的 clientId

// 启动引力引擎
GravityEngineAPI.StartGravityEngine(accessToken, clientId, GravityEngineAPI.SDKRunMode.NORMAL, "appstore");

// 开启事件自动采集
GravityEngineAPI.EnableAutoTrack(AUTO_TRACK_EVENTS.APP_ALL, new Dictionary<string, object>());

请一定注意，不要忘记第一步挂载脚本！很多接入报错都是这个原因导致！

3.初始化

在可以获取到用户唯一性信息时调用本方法，推荐首次安装启动时调用，后续其他方法均需在本方法回调成功之后才可正常使用。

Android/小游戏/快游戏

public class InitializeCallbackImpl : IInitializeCallback
{
    // 初始化失败之后回调，errorMsg为报错信息
    public void onFailed(string errorMsg)
    {
        Debug.Log("initialize failed  with message " + errorMsg);
    }

    // 初始化成功之后回调
    public void onSuccess()
    {
        Debug.Log("initialize success");
        Debug.Log("initialize call end");
        // 建议在此执行一次Flush
        GravityEngineAPI.Flush();
    }
}

/// <summary>
/// 在引力引擎初始化，后续其他方法均需在本方法回调成功之后才可正常使用
/// </summary>
/// <param name="clientId"></param>                 用户唯一标识
/// <param name="nickname"></param>                 用户昵称
/// <param name="version"></param>                  用户注册的程序版本，比如当前小游戏的版本号
/// <param name="openId"></param>                   open id (小程序/小游戏必填)
/// <param name="enableSyncAttribution"></param>    是否开启同步获取归因信息，具体请参考同步归因：https://doc.gravity-engine.com/turbo-integrated/sync_attribution.html
/// <param name="initializeCallback"></param>       网络回调，其他方法均需在回调成功之后才可正常使用
/// <exception cref="ArgumentException"></exception>
GravityEngineAPI.Initialize("your_user_client_id", "name_123", 1, "your_openid_111", false, new InitializeCallbackImpl());

针对 clientId 参数，您需要特殊注意

如果产品为小游戏：则必须填用户的 openid （如传空，则使用调用 StartGravityEngine 时传入的 clientId）

如果产品为 Android：则传入用户唯一ID，例如 UID 或者设备 ID（如传空，则引力 sdk 内部会自动采集设备 id 填入，采集优先级顺序为：oaid > android_id > imei，如果所有id 都采集不到时，会生成随机的 16 位 id 保存到本地缓存中以保持相对稳定）

针对 nickname 参数，您需要特殊注意

如果产品为 Android：如果传空，则引力 sdk 内部会自动根据 client_id 计算 md5 生成

public class InitializeCallbackImpl : IInitializeCallback
{
    // 初始化失败之后回调，errorMsg为报错信息
    public void onFailed(string errorMsg)
    {
        Debug.Log("initialize failed  with message " + errorMsg);
    }

    // 初始化成功之后回调
    public void onSuccess()
    {
        Debug.Log("initialize success");
        Debug.Log("initialize call end");
        // 建议在此执行一次Flush
        GravityEngineAPI.Flush();
    }
}

/// <summary>
/// 在引力引擎注册，后续其他方法均需在本方法回调成功之后才可正常使用（iOS专用）
/// </summary>
/// <param name="enableAsa"></param>                是否开启asa归因
/// <param name="clientId"></param>                 用户在引力系统中的唯一标识，如果传空字符串，则引力 sdk 内部会采集一个稳定的 idfv 作为用户唯一标识（推荐传空字符串）
/// <param name="caid1MD5"></param>                 当前用户中广协 ID 的 md5 hash（20230330 版本）（可为空）
/// <param name="caid2MD5"></param>                 当前用户中广协 ID 的 md5 hash（20250325 版本）（可为空字符串）
/// <param name="enableSyncAttribution"></param>    是否开启同步获取归因信息，具体请参考同步归因：https://doc.gravity-engine.com/turbo-integrated/sync_attribution.html
/// <param name="initializeCallback"></param>       网络回调，其他方法均需在回调成功之后才可正常使用
/// <exception cref="ArgumentException"></exception>
GravityEngineAPI.InitializeIOS(false, clientId, caid1Md5, caid2Md5, false, new InitializeCallbackImpl());

openId：微信和抖音、快手小游戏此参数为必填项，是买量归因必须的参数，请注意一定传入！

首次调用后，需要等 IInitializeCallback 的 onSuccess 回调之后才能继续调用其他事件上报的方法，否则会上报失败！

用户整个生命周期内，初始化接口只需要调用一次，调用成功之后，后续冷启动可以不再调用，只需要保证 SDK 正确执行初始化逻辑即可（多次调用也不会有问题，引力做了兼容）。

4.事件上报

4.1 业务注册事件上报

如果您的应用不需要追踪用户注册行为，可以跳过此事件接入。此功能仅适用于需要统计业务注册转化数据的场景。

该方法可多次调用，每次调用都会上报一个用户注册事件（计算指标时会去重）

当用户完成应用内业务注册后，您可以调用 trackRegisterEvent 方法来上报用户注册事件(APP:$AppRegister/小游戏：$MPRegister)给引力，引力会使用该事件统计后台计算指标：标准_注册数

调用示例

// 小游戏/快游戏
GravityEngineAPI.TrackMPRegister();

// Android/iOS
GravityEngineAPI.TrackAppRegister();

4.2 付费事件上报

付费事件上报用于收入统计和分析，如您的应用不涉及内购或付费服务，则无需接入此事件。

如果您需要通过后端 API 方式上报付费事件，请参考混合上报模式来接入事件上报接口报送付费事件。

当用户发生付费行为时，需要调用 trackPayEvent 方法记录用户付费事件，此事件非常重要，会影响买量和 ROI 统计，请务必重点测试！

方法示例

public static string TrackPayEvent(int payAmount, string payType, string orderId, string payReason, string payMethod)

参数说明

参数名称	参数含义	参数类型	是否必传
payAmount	付费金额单位为分。请务必注意，传错单位可能会导致买量受到影响！	int	是
payType	货币类型按照国际标准组织ISO 4217中规范的3位字母，例如CNY人民币、USD美金等，具体请参考：国际标准组织 ISO 4217 代码表	string	是
orderId	订单号。引力引擎会通过订单号去重，避免重复上报，请务必准确传入！	string	是
payReason	付费原因例如：购买钻石、办理月卡	string	是
payMethod	付费方式例如：支付宝、微信、银联等	string	是

返回值

返回值为当前事件生成的事件 trace_id

调用示例

GravityEngineAPI.TrackPayEvent(300, "CNY", "your_order_id", "月卡", "支付宝");

4.3 广告观看事件上报

广告观看上报适用于广告变现类应用，若您的应用未集成广告模块，则无需接入此事件。

微信小游戏产品需要参照 微信广告变现实时统计 一文，检查是否正确配置微信 access_token ，配置错误将无法正确获取微信小游戏广告变现数据！

抖音小游戏、快手小游戏、B 站小游戏无需接入，会由引力后端自动拉取，具体配置，请参考这里

若您的产品内有广告变现，则需要在用户点击广告观看的同时上报用户广告观看事件给引力，具体参考如下：

方法示例

Android/iOS

public static void TrackNativeAppAdShowEvent(string adUnionType, string adPlacementId, string adSourceId, string adType, string adnType, float ecpm)

为生成准确的广告收益分析报表，请尽量遵循规范填写下方的广告平台参数。正确的字段是生成有价值报表的基础。

我们为您准备了详细的指引： 👉 广告聚合平台字段配置说明

参数名称	参数含义	参数类型	是否必传
adUnionType	广告聚合平台类型（取值为：topon、gromore、admore、self，分别对应Topon、Gromore、Admore、自建聚合）	string	是
adPlacementId	广告瀑布流ID（广告位ID）	string	是
adSourceId	广告源ID（代码位ID）	string	是
adType	广告类型（取值为：reward、banner、 native 、interstitial、 splash ，分别对应激励视频广告、横幅广告、信息流广告、插屏广告、开屏广告）	string	是
adnType	广告平台类型（取值为：csj、gdt、ks、 mint 、baidu，分别对应为穿山甲、优量汇、快手联盟、Mintegral、百度联盟）	string	是
ecpm	预估ECPM价格（千次展示收入（单位元））	float	是

小游戏/快游戏

public static void TrackWechatAdShowEvent(string adType, string adUnitId, Dictionary<string, object> otherProperties = null)

为生成准确的广告收益分析报表，请尽量遵循规范填写下方的广告平台参数。正确的字段是生成有价值报表的基础。

我们为您准备了详细的指引： 👉 广告聚合平台字段配置说明

参数名称	参数含义	参数类型	是否必传
adType	广告类型（取值为：reward、banner、native、interstitial、video_feed、video_begin，分别对应激励视频广告、Banner广告、原生模板广告、插屏广告、视频广告、视频贴片广告）	string	是
adUnitId	广告位ID（一般以adunit开头，注意不要填错，会导致广告收入统计不准！）	string	是
otherProperties	自定义参数。其他需要携带的自定义参数，需要提前在引力后台元数据管理中针对广告观看($AdShow) 事件配置好相关属性，比如快游戏上报广告 ecpm，可以使用引力预置好的属性字段：$ecpm，具体见下发代码示例。	Dictionary<string, object>	否

调用示例

Android/iOS

GravityEngineAPI.TrackNativeAppAdShowEvent("topon", "placement_id", "ad_source_id", "reward", "csj", 1);

小游戏/快游戏

var otherProperties = new Dictionary<string, object>()
{
    {"$ecpm", 10000}, // 本次广告曝光的 ECPM
    {"other_key", "other_value"} // 其他想携带的属性信息
};
GravityEngineAPI.TrackMiniGameAdShowEvent("reward", "your_ad_unit_id", otherProperties);

5.接入验证

正式上线之前，请完成本节的校验，否则可能会导致买量上报异常！

5.1 开启 Debug 模式

SDK 支持在两种模式下运行：

NORMAL: 普通模式，数据会存入缓存，并依据一定的缓存策略上报
DEBUG: 测试模式，数据逐条上报。当出现问题时会以日志和异常的方式提示用户，也可以去引力网站后台--设置--元数据--事件流中查看实时上报的数据，辅助您判断数据接入是否正常。

您在调用 StartGravityEngine 初始化引擎时，可以传入 SDKRunMode 参数来指定 SDK 运行模式。

Debug 模式仅仅用于集成阶段数据校验，不要在正式环境下使用！上线前请关闭！

5.2 关键事件验证

在 SDK 中开启 Debug 模式，并依次在产品中触发以下几个事件。

事件名	事件英文名	触发时机	采集方式	默认映射到媒体事件	备注
用户注册	APP:`$AppRegister` 小游戏:`$MPRegister`	用户完成业务注册之后	调用SDK的上报业务注册事件方法采集	暂无	接入了业务注册上报事件的产品均需要校验
付费	`$PayEvent`	用户付费之后	调用 SDK 的上报用户付费事件方法采集	付费	接入了付费事件上报事件的的产品均需要校验
广告展示	`$AdShow`	用户观看广告之后	调用 SDK 的上报广告展示事件方法采集	暂无	接入了广告事件上报事件的产品均需要校验
用户提现	`$UserWithdraw`	用户提现之后	调用 SDK 的上报用户提现事件方法采集	暂无	接入了用户提现上报事件的产品均需要校验

测试完成之后，在事件流界面过滤测试用户的 Client ID ，查看对应事件的校验状态是否为 "校验通过" ，当事件有数据并且状态为校验通过后，则表明接入成功。

5.3 避免重复上报

如果您之前单独接了媒体的回传(SDK 或者 API)，则上线之前需要去掉，否则可能会导致重复上报数据！

至此验证无误之后，您可以正常上线了。

上一个

Unity

下一个

行为事件上报

最近修改: 2025-09-25Powered by

快速集成

​​Unity SDK 平台集成说明​​

​​1. 微信小游戏平台 ✅​​

​​2. 其他平台 ❌​​

1. SDK 基础配置

1.1 SDK 引入

1.1.1 iOS配置（仅iOS应用需要配置）

1.2 添加全局宏参数

2.配置并启动 SDK

小游戏/快游戏

Android

iOS

3.初始化

Android/小游戏/快游戏

iOS

4.事件上报

4.1 业务注册事件上报

调用示例

4.2 付费事件上报

方法示例

参数说明

返回值

调用示例

4.3 广告观看事件上报

方法示例

调用示例

5.接入验证

5.1 开启 Debug 模式

5.2 关键事件验证

5.3 避免重复上报

Unity SDK 平台集成说明

1. 微信小游戏平台 ✅

2. 其他平台 ❌