# 快速集成
> 来源：https://help.gravity-engine.com/docs/client-sdk/unity/quickstart
> 介绍 Gravity Engine Unity SDK 的安装、初始化、用户注册与事件上报流程，并提供参数说明和调用示例。
本文档为**Unity**接入 [引力引擎](https://gravity-engine.com/)的技术接入方案，具体 Demo 请参考[GitHub](https://github.com/GravityInfinite/GravityEngine-Unity-Demo)开源项目，Demo 工程中可以参考 `GravityEngineDemo.cs` 脚本中对每一个方法的调用示例。
在开始接入前，建议您先阅读 [接入前准备](/docs/getting-started/overview)以了解接入必备的基础概念。
## 1. SDK 基础配置 [#1-sdk-基础配置]
> **注意**
> **微信小游戏：需要先参考微信团队发布的**[微信小游戏适配方案](https://developers.weixin.qq.com/minigame/dev/guide/game-engine/unity-webgl-transform.html)。
>
> **抖音小游戏：需要先接入头条提供的**[StarkSDK 插件](https://bytedance.feishu.cn/docx/doxcnTom4J47auHMnkjGYMBaNnZ)。
>
> **快手小游戏：需要先接入快手提供的 SDK 插件**，[详情参考](https://docs.qingque.cn/d/home/eZQCBgxB_tDpuSKJUAmmgeUcW?identityId=1oEEcs7JzPQ#section=h.sh36jfgvy7tb)。
### 1.1 接入步骤 [#11-接入步骤]
#### 1.1.1 导入UnityPackage [#111-导入unitypackage]
> **注意**
> **使用低版本(5.0.24及之前)插件的客户, 要升级到5.0.25(或以上版本)，可参考[UnitySDK 升级方案](/docs/client-sdk/unity/sdk-upgrade)**
下载最新的 [`GravityEngine.unitypackage`](/docs/client-sdk/sdk-overview)，通过 `Assets > Import Package > Custom Package`导入。
#### 1.1.2 SDK配置 [#112-sdk配置]
**国内**：默认为国内。如需切换，可在unity菜单->引力引擎->使用国内SDK进行切换\*\*海外：\*\*导入unitypackage后，unity菜单->引力引擎->使用海外SDK
#### 1.1.3 插件自动集成 [#113-插件自动集成]
**详细操作请参考：**《[EDM4U插件使用说明](/docs-assets/attachments/NbeTxLdb/EDM4U%E8%87%AA%E5%8A%A8%E9%9B%86%E6%88%90%E4%BD%BF%E7%94%A8%E4%BA%8B%E9%A1%B9.zip "EDM4U自动集成使用事项")》文档
导入后包含以下关键文件夹：
**📁 `Assets/ExternalDependencyManager`**
* **作用**：[EDM4U](https://github.com/googlesamples/unity-jar-resolver)插件（用于自动依赖管理）
* **处理**：如果项目已使用该插件，导入时可跳过此文件夹
**📁 `Assets/GravityNet`**
* **作用**：[EDM4U](https://github.com/googlesamples/unity-jar-resolver)插件自动接入底层SDK的配置
* **处理**：如果明确不需要[EDM4U](https://github.com/googlesamples/unity-jar-resolver)插件方式，可不导入此文件夹，但需要参照[iOS](/docs/client-sdk/ios/quickstart#2-%E9%9B%86%E6%88%90%E5%BC%95%E5%8A%9B%E5%BC%95%E6%93%8E-sdk)和[Android](/docs/client-sdk/android/quickstart#22-%E6%89%8B%E5%8A%A8%E9%9B%86%E6%88%90)的接入文档手动导入底层SDK
* **特殊情况**：使用[EDM4U](https://github.com/googlesamples/unity-jar-resolver)插件自动接入失败（如unity版本不支持该插件,iOS没有cocoapods环境等），也需要参照[iOS](/docs/client-sdk/ios/quickstart#2-%E9%9B%86%E6%88%90%E5%BC%95%E5%8A%9B%E5%BC%95%E6%93%8E-sdk)和[Android](/docs/client-sdk/android/quickstart#22-%E6%89%8B%E5%8A%A8%E9%9B%86%E6%88%90)的接入文档手动导入底层SDK。
#### 1.1.4 手动集成 [#114-手动集成]
参考[UnitySDK 升级方案](/docs/client-sdk/unity/sdk-upgrade) 里的非插件引入方式
#### 1.1.5 SDK冲突说明 [#115-sdk冲突说明]
如果原工程已经接入了华为或荣耀SDK，导致接入我们SDK后出现编译失败，可以编辑`Assets/GravityNet/GravityPlugins/Oaid/Editor/Dependencies.xml`文件，移除对应冲突的SDK
### 1.2 iOS配置（仅iOS应用需要配置） [#12-ios配置仅ios应用需要配置]
找到 Targets，在 Build Settings 菜单的 `Other linker flags` 选项添加 `-ObjC`
切换到 `Build Phases` 选项卡，在 `Link Binary With Libraries` 栏目下添加如下依赖项：
1. `libz.tbd`
2. `Security.framework`
3. `AdServices.framework`（optional 形式引入）
4. `SystemConfiguration.framework`
5. `libsqlite3.tbd`
6. `AppTrackingTransparency.framework`（获取 idfa 需要）
7. `AdSupport.framework`（获取 idfa 需要）
> **注意**
> **以上依赖项，必须全部添加，否则会导致编译失败！**
### 1.3 Harmony配置 [#13-harmony配置]
* 鸿蒙只支持国内，unity必须使用unity国内版 《团结引擎》
* 鸿蒙底层SDK，需要手动集成SDK
1. 方式一：集成方式参考[HarmonyOS接入文档](/docs/client-sdk/harmonyos/quickstart) 第一步下载安装
2. 方式二：下载鸿蒙底层har包，放到`/Assets/Plugins/OpenHarmony/gravityengine.har`目录下
* TuanjiePlayerAbilityBase 类里，onCreate方法（可选，仅支持接入方式一，如果需要[元服务App Linking跟踪](https://developer.huawei.com/consumer/cn/doc/promotion/ads-applink-0000002131566034)（want.parameters）需设置）
```ts
import { GravityEngineUnityChannel } from '../GravityEngineUnityChannel';
export class TuanjiePlayerAbilityBase extends UIAbility {
onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
GravityEngineUnityChannel.onUnityAppStart(this.context,want.parameters);
}
}
```
### 1.4 添加全局宏参数 [#14-添加全局宏参数]
正式接入之前，您需要针对不同的平台添加不同的全局宏参数，目前引力 Unity SDK 支持以下平台：
| **支持平台** | **宏参数** | **备注** |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 
微信小游戏 | GRAVITY\_WECHAT\_GAME\_MODE | |
| 
抖音小游戏 | GRAVITY\_BYTEDANCE\_GAME\_MODE | |
| 
抖音小游戏 TT SDK 模式/Tiktok | GRAVITY\_BYTEDANCE\_TT\_GAME\_MODE | 如您已升级到 TT SDK，使用本模式，详情请参考[抖音小游戏 SDK 官方文档](https://developer.open-douyin.com/docs/resource/zh-CN/mini-game/develop/guide/game-engine/rd-to-SCgame/unity-game-access/starksdk-migration-guide) |
| 抖音云游戏 | GRAVITY\_BYTEDANCE\_CLOUD\_MODE | |
| 
快手小游戏 | GRAVITY\_KUAISHOU\_GAME\_MODE | |
| 
快手小游戏 WEBGL | GRAVITY\_KUAISHOU\_WEBGL\_GAME\_MODE | 如果使用的老版本webGLSDK，请添加宏 **KUAISHOU\_WEBGL\_BELOW\_TUANJIE\_VERSION** 建议更新到最新版本的快手webGLSDK 更新参考：[快手官方文档](https://docs.qingque.cn/d/home/eZQAIID-S92Rd6hhqyS-jkXnK?identityId=2G5RW70GDUS#section=h.ld785qehdds5) |
| 
支付宝小游戏 | GRAVITY\_ALIPAY\_GAME\_MODE | |
| 
美团小游戏 | GRAVITY\_MEITUAN\_GAME\_MODE | |
| 
Bilibili 小游戏 | GRAVITY\_BILIBILI\_GAME\_MODE | |
| 
TapTap小游戏 | GRAVITY\_TAPTAP\_GAME\_MODE | |
| 
华为快游戏 | GRAVITY\_HUAWEI\_GAME\_MODE | |
| 
OPPO 快游戏 | GRAVITY\_OPPO\_GAME\_MODE | 其他修改请参考[这篇文档](https://gravityengine.feishu.cn/docx/IYwmdeEsho9XxGxSVhEcXJ7JnEf) |
| 
小米快游戏 | GRAVITY\_XIAOMI\_GAME\_MODE | 其他修改请参考[这篇文档](https://dev.mi.com/xiaomihyperos/documentation/detail?pId=1991) |
| VIVO快游戏 | GRAVITY\_VIVO\_GAME\_MODE | |
| 
Android | 无需配置宏参数 | |
| 
iOS | 无需配置宏参数 | |
| 
Harmony | 无需配置宏参数 | |
| 
Windows | 无需配置宏参数 | |
1. 手动添加，添加步骤如下：
* 打开 Project Settings 界面；
* 找到 `Scripting Define Symbols`，新增一行输入对应平台的全局宏参数，然后点击 Apply 按钮完成设置
2. 通过可视化界面添加
> **注意**
> **请确保正式打包上线时，选中的宏参数依然正常生效，否则会影响到对应平台的事件上报，影响买量效果！**
## 2. 配置并启动 SDK [#2-配置并启动-sdk]
请参考以下代码来进行 SDK 的初始化，建议在能够获取到用户唯一 ID，如小游戏的`openId`、Android 设备的`oaid`、iOS 设备的`IDFV`时，尽早的进行初始化。
### 通用启动方法 [#通用启动方法]
> **注意**
> **配置项目合法域名**
>
> **如果您的项目为小游戏，您需要将** `https://backend.gravity-engine.com` **和** `https://api.gravity-engine.com` **配置到后台 request 合法域名列表中。**
>
> **tiktok 海外合法域名：`https://global-api.gravity-engine.com`**
> **注意**
> **如果您是从低版本引力 sdk 升级到高版本的，请一定记得添加**`https://api.gravity-engine.com`**域名到合法域名列表中，否则将导致事件采集失效，影响您的使用！**
**方法 1（代码创建配置）**
```csharp
// 手动初始化（动态挂载 GravityEngineAPI 脚本）
new GameObject("GravityEngine", typeof(GravityEngineAPI));
// Android原生应用示例
//设置实例参数并启动引擎，将以下三个参数修改成您应用对应的参数，参数可以在引力后台--设置--应用管理中查看
string accessToken = "your_access_token"; // 项目通行证，在：网站后台-->设置-->应用列表中找到Access Token列 复制（首次使用可能需要先新增应用）
string clientId = "default_placeholder"; // Android/iOS 传入固定值：default_placeholder，小游戏为用户OpenID
string channel = "base_channel"; // 安装包渠道来源，比如xiaomi、huawei、应用宝
GravityEngineAPI.Token token = new GravityEngineAPI.Token(accessToken, clientId,channel );
//token配置
token.isChina = true;// 是否使用国内域名，默认为true
token.enableImei = true; // 是否采集imei，仅支持Android，默认true（选填,5.0.23 以上版本支持）
token.enableOaid = true; // 是否采集oaid，仅支持Android，默认true（选填,5.0.23 以上版本支持）
token.enableAndroidId = true; // 是否采集android_id，仅支持Android，默认true（选填,5.0.23 以上版本支持）
token.enableMac = true; // 是否采集mac，仅支持Android，默认true（选填,5.0.24 以上版本支持）
//预设公共属性
token.presetSuperProperties = new Dictionary()
{
{"testSuperKey", "testSuperValue"}
};
//Android设备clientID优先级顺序，默认优先取 OAID 为clientId
token.mClientIdPriorityOrder = new List(){
GravityEngineAPI.AndroidClientIdType.OAID, GravityEngineAPI.AndroidClientIdType.ANDROID_ID};
// 启动引力引擎
GravityEngineAPI.StartGravityEngine(token);
```
> **注意**
> 通过 **非自建中台** 的方式导入历史用户到引力时，默认以 Android\_ID 作为 `clientID`。SDK 需通过 `mClientIdPriorityOrder` 将 `clientID` 生成顺序设为 **ANDROID\_ID 优先**，与导入规则保持一致，否则同一设备会被算作两个用户。
##### Token可选参数 [#token可选参数]
| **参数名** | **说明** | **是否必需** | **默认值** | **地区** | **适用平台** | **版本要求/备注** |
| -------------------------- | -------------------- | -------- | ------- | ------ | ----------- | ----------- |
| isChina | 是否使用国内域名 | 否 | TRUE | 通用 | 全平台 | 5.0.35+ |
| enableImei | 是否采集IMEI | 否 | TRUE | 国内 | Android | 5.0.23+ |
| enableOaid | 是否采集OAID | 否 | TRUE | 国内 | Android | 5.0.23+ |
| enableAndroidId | 是否采集Android ID | 否 | TRUE | 国内 | Android | 5.0.23+ |
| enableMac | 是否采集MAC地址 | 否 | TRUE | 国内 | Android | 5.0.24+ |
| presetSuperProperties | 预设公共属性 | 否 | - | 通用 | 全平台 | 5.0.42+ |
| mClientIdPriorityOrder | Android ClientID取值顺序 | 否 | - | 通用 | Android | 5.0.30+ |
| foregroundSessionThreshold | 前台会话阀值 | 否 | 0 | 通用 | Android/iOS | 设置前台会话阀值 |
| isGDPRArea | 是否欧盟地区（GDPR合规） | 否 | FALSE | 海外 | Android/iOS | 欧盟地区需设为true |
| isCoppaEnabled | 是否COPPA法案合规 | 否 | FALSE | 海外 | Android/iOS | 美国儿童应用合规 |
| isKidsAppEnabled | 是否儿童应用 | 否 | FALSE | 海外 | Android/iOS | 目标用户\<13周岁 |
| adPersonalizationEnabled | 是否允许个性化广告 | 否 | FALSE | 海外 | Android | Google广告相关 |
| adUserDataEnabled | 是否允许数据发送到Google | 否 | FALSE | 海外 | Android | Google广告相关 |
| fbAppID | Facebook应用ID | 否 | 空字符串 | 海外 | Android | Facebook归因 |
**方法 2（可视化界面配置）**
```csharp
// 手动初始化（动态挂载 GravityEngineAPI 脚本）
new GameObject("GravityEngine", typeof(GravityEngineAPI));
// Android原生应用示例
//设置实例参数并启动引擎，将以下三个参数修改成您应用对应的参数，参数可以在引力后台--设置--应用管理中查看
string clientId = "default_placeholder"; // Android/iOS 传入固定值：default_placeholder，小游戏为用户OpenID
// 启动引力引擎,国内
GravityEngineAPI.AutoStartGravityEngine(clientId);
// 启动引力引擎,海外
//如果你的应用在欧盟地区运营并且在Google投放您的应用，请务必将用户是否允许Google将其数据用于个性化广告的意见结果传入该属性，以确保您符合Google对欧盟用户意见征求政策的新政策仅支持 （选填）仅支持Android
//bool adPersonalizationEnabled = false;
//如果你的应用在欧盟地区运营并且在Google投放您的应用，请务必将用户是否同意将其数据发送到Google的意见结果传入该属性，以确保您符合Google对欧盟用户意见征求政策的新政策（选填）仅支持 Android
//bool adUserDataEnabled = false;
//GravityEngineAPI.AutoStartGravityEngine(clientId , adPersonalizationEnabled ,adUserDataEnabled);
```
### 非通用启动方法 [#非通用启动方法]
**小游戏/快游戏/Windows**
```csharp
// 手动初始化（动态挂载 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);
```
> **注意**
> **配置项目合法域名**
>
> **如果您的项目为小游戏，您需要将** `https://backend.gravity-engine.com` **和** `https://api.gravity-engine.com` **配置到后台 request 合法域名列表中。**
>
> **tiktok 海外合法域名：`https://global-api.gravity-engine.com`**
> **注意**
> **如果您是从低版本引力 sdk 升级到高版本的，请一定记得添加**`https://api.gravity-engine.com`**域名到合法域名列表中，否则将导致事件采集失效，影响您的使用！**
**Android（国内）**
```csharp
// 手动初始化（动态挂载 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、应用宝
bool enableImei = true; // 是否采集imei，仅支持Android，默认true（选填,5.0.23 以上版本支持）
bool enableOaid = true; // 是否采集oaid，仅支持Android，默认true（选填,5.0.23 以上版本支持）
bool enableAndroidId = true; // 是否采集android_id，仅支持Android，默认true（选填,5.0.23 以上版本支持）
bool enableMac = true; // 是否采集mac，仅支持Android，默认true（选填,5.0.24 以上版本支持）
// 启动引力引擎
GravityEngineAPI.StartGravityEngine(accessToken, clientId, GravityEngineAPI.SDKRunMode.NORMAL, channel, enableImei, enableOaid, enableAndroidId,enableMac );
```
**Android（海外）**
```csharp
// 手动初始化（动态挂载 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、应用宝
bool isGDPRArea = false; //是否欧盟地区 选调，默认false 如果你的应用在欧盟地区运营，则需要符合欧盟隐私保护法律的规定（关于GDPR），请务必在用户拒绝采集设备敏感信息时设置
bool isCoppaEnabled = false; //是否需要符合《儿童在线隐私权保护法》 选调，默认false 如果您的应用需要符合《儿童在线隐私权保护法》(COPPA) 规定，设置 isCoppaEnabled = true（选填）
bool isKidsAppEnabled = false; //是否儿童应用 选调，默认false 如果您的应用会定向到不满 13 周岁的儿童，则需要将其标记为儿童应用 (Kids App)，设置 isKidsAppEnabled = true（选填）
bool adPersonalizationEnabled = false; //户是否允许Google将其数据用于个性化广告的意见结果 选调，默认false 如果你的应用在欧盟地区运营并且在Google投放您的应用，请务必将用户是否允许Google将其数据用于个性化广告的意见结果传入该属性，以确保您符合Google对欧盟用户意见征求政策的新政策
bool adUserDataEnabled = false; //用户是否同意将其数据发送到Google的意见结果 选调，默认false 如果你的应用在欧盟地区运营并且在Google投放您的应用，请务必将用户是否同意将其数据发送到Google的意见结果传入该属性，以确保您符合Google对欧盟用户意见征求政策的新政策
string fbAppID = ""; //应用Facebook appId 选调，默认"" 如果您的应用需要进行Facebook归因，请设置你的FacebookID
// 启动引力引擎
GravityEngineAPI.StartOverseaGravityEngine(accessToken, clientId, GravityEngineAPI.SDKRunMode.NORMAL, channel, isGDPRArea, isCoppaEnabled, isKidsAppEnabled,adPersonalizationEnabled,adUserDataEnabled,fbAppID);
```
**iOS（国内）**
```csharp
// 手动初始化（动态挂载 GravityEngineAPI 脚本）
new GameObject("GravityEngine", typeof(GravityEngineAPI));
// iOS原生应用示例
//设置实例参数并启动引擎，将以下参数修改成您应用对应的参数，参数可以在引力后台--设置--应用管理中查看
string accessToken = "your_access_token";
string clientId = "default_placeholder"; // 固定值：default_placeholder
// 启动引力引擎
GravityEngineAPI.StartGravityEngine(accessToken, clientId, GravityEngineAPI.SDKRunMode.NORMAL, "appstore");
```
**iOS（海外）**
```csharp
// 手动初始化（动态挂载 GravityEngineAPI 脚本）
new GameObject("GravityEngine", typeof(GravityEngineAPI));
// iOS原生应用示例
//设置实例参数并启动引擎，将以下参数修改成您应用对应的参数，参数可以在引力后台--设置--应用管理中查看
string accessToken = "your_access_token";
string clientId = "default_placeholder"; // 固定值：default_placeholder
bool isGDPRArea = false; //是否欧盟地区 选调，默认false 如果你的应用在欧盟地区运营，则需要符合欧盟隐私保护法律的规定（关于GDPR），请务必在用户拒绝采集设备敏感信息时设置
bool isCoppaEnabled = false; //是否需要符合《儿童在线隐私权保护法》 选调，默认false 如果您的应用需要符合《儿童在线隐私权保护法》(COPPA) 规定，设置 isCoppaEnabled = true（选填）
bool isKidsAppEnabled = false; //是否儿童应用 选调，默认false 如果您的应用会定向到不满 13 周岁的儿童，则需要将其标记为儿童应用 (Kids App)，设置 isKidsAppEnabled = true（选填）
// 启动引力引擎
GravityEngineAPI.StartOverseaGravityEngine(accessToken, clientId, GravityEngineAPI.SDKRunMode.NORMAL, "appstore", isGDPRArea, isCoppaEnabled, isKidsAppEnabled);
```
> **注意**
> **请一定注意，不要忘记第一步挂载脚本！很多接入报错都是这个原因导致！**
## 3. 初始化 [#3-初始化]
在可以获取到用户唯一性信息时调用本方法，推荐首次安装启动时调用，后续其他方法均需在本方法回调成功之后才可正常使用。
**Android/小游戏/快游戏/Windows**
```csharp
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();
}
}
///
/// 在引力引擎初始化，后续其他方法均需在本方法回调成功之后才可正常使用
///
/// 用户唯一标识
/// 用户昵称
/// 用户注册的程序版本，比如当前小游戏的版本号
/// open id (小程序/小游戏必填)
/// 是否开启同步获取归因信息，在媒体点击下发延迟的情况下会影响归因，请谨慎开启。具体请参考同步归因：/docs/attribution/synchronous-attribution
/// 网络回调，其他方法均需在回调成功之后才可正常使用
///
GravityEngineAPI.Initialize("your_user_client_id", "name_123", 1, "your_openid_111", false, new InitializeCallbackImpl());
```
> **注意**
> **针对 clientId 参数，您需要特殊注意**
>
> 1. **如果产品为小游戏：则必须填用户的 openid （如传空，则使用调用 StartGravityEngine 时传入的 clientId）**
> 2. **如果产品为 Android：则传入用户唯一ID，例如 UID 或者设备 ID（如传空(需unity SDK版本大于5.0.31)，则引力 sdk 内部会自动采集设备 id 填入，采集优先级顺序为：oaid > android\_id > imei，如果所有id 都采集不到时，会生成随机的 16 位 id 保存到本地缓存中以保持相对稳定）**
>
> **如果产品为小游戏且没有自建后端，无法自行获取 openid 时，可参考[快捷获取 openid](/docs/client-sdk/unity/advanced/quick-get-openid)。**
>
> **针对 nickname 参数，您需要特殊注意**
>
> 1. **如果产品为 Android：如果传空，则引力 sdk 内部会自动根据 client\_id 计算 md5 生成**
**iOS**
```csharp
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();
}
}
///
/// 在引力引擎注册，后续其他方法均需在本方法回调成功之后才可正常使用（iOS专用）
///
/// 是否开启 ASA 广告采集，建议传 YES 以开启归因采集能力，后续可由引力后台的归因配置开关控制是否开启ASA归因。
/// 用户在引力系统中的唯一标识，如果传空字符串，则引力 sdk 内部会采集一个稳定的 idfv 作为用户唯一标识（推荐传空字符串）
/// 当前用户中广协 ID, 类型为json字符串，数组里面是字典，字典里有version和caid字段(可以为空字符串)
/// 是否开启同步获取归因信息，具体请参考同步归因：/docs/attribution/synchronous-attribution
/// 网络回调，其他方法均需在回调成功之后才可正常使用
///
GravityEngineAPI.InitializeIOS(true, clientId,CAID_STR, false, new InitializeCallbackImpl());
```
> **注意**
> * **`openId`**：微信和抖音、快手小游戏此参数为必填项，是买量归因必须的参数，请注意一定传入！
> * **首次调用后，需要等** `IInitializeCallback` **的** `onSuccess` **回调之后才能继续调用其他事件上报的方法，否则会上报失败！**
> * **用户整个生命周期内，初始化接口只需要调用一次，调用成功之后，后续冷启动可以不再调用，只需要保证 SDK 正确执行初始化逻辑即可**（多次调用也不会有问题，引力做了兼容）。
## 4. 事件上报 [#4-事件上报]
### 4.1 业务注册事件上报 [#41-业务注册事件上报]
> **注意**
> **如果您的应用不需要追踪用户注册行为，可以跳过此事件接入。此功能仅适用于需要统计业务注册转化数据的场景。**
> **注意**
> 该方法可多次调用，每次调用都会上报一个用户注册事件（计算指标时会去重）
当用户完成应用内业务注册后，您可以调用 `trackRegisterEvent` 方法来上报用户注册事件(APP:`$AppRegister`/小游戏：`$MPRegister`)给引力，引力会使用该事件统计后台计算指标：标准\_注册数
#### 调用示例 [#调用示例]
**Android/iOS**
```csharp
GravityEngineAPI.TrackAppRegister();
```
**小游戏/快游戏**
```csharp
GravityEngineAPI.TrackMPRegister();
```
### 4.2 付费事件上报 [#42-付费事件上报]
> **注意**
> **付费事件上报用于收入统计和分析，如您的应用不涉及内购或付费服务，则无需接入此事件。**
> **注意**
> 如果您需要通过后端 API 方式上报付费事件，请参考 [混合上报模式](/docs/client-sdk/hybrid-reporting) 来接入事件上报接口报送付费事件。
当用户发生付费行为时，需要调用 `trackPayEvent` 方法记录用户付费事件，此事件非常重要，会影响买量和 ROI 统计，请务必重点测试！
#### 方法示例 [#方法示例]
```csharp
public static string TrackPayEvent(int payAmount, string payType, string orderId, string payReason, string payMethod)
```
#### 参数说明 [#参数说明]
| **参数名称** | **参数含义** | **参数类型** | **是否必传** |
| --------- | ----------------------------------------------------------------------------------------------------------------- | -------- | -------- |
| payAmount | 付费金额 单位为分。请务必注意，传错单位可能会导致买量受到影响！ | int | 是 |
| payType | 货币类型 按照国际标准组织ISO 4217中规范的3位字母，例如CNY人民币、USD美金等，具体请参考：[国际标准组织 ISO 4217 代码表](https://en.wikipedia.org/wiki/ISO_4217) | string | 是 |
| orderId | 订单号。引力引擎会通过订单号去重，避免重复上报，请务必准确传入！ | string | 是 |
| payReason | 付费原因 例如：购买钻石、办理月卡 | string | 是 |
| payMethod | 付费方式 例如：支付宝、微信、银联等 | string | 是 |
#### 返回值 [#返回值]
返回值为当前事件生成的事件 trace\_id
#### 调用示例 [#调用示例-1]
```csharp
GravityEngineAPI.TrackPayEvent(300, "CNY", "your_order_id", "月卡", "支付宝");
```
### 4.3 广告观看事件上报 [#43-广告观看事件上报]
> **注意**
> **广告观看上报适用于广告变现类应用，若您的应用未集成广告模块，则无需接入此事件。**
> **注意**
> **微信小游戏产品需要参照** **[微信广告变现实时统计](/docs/server-integration/mini-game-tokens/wechat-monetization-stats)** **一文，检查是否正确配置微信** **`access_token`** **，配置错误将无法正确获取微信小游戏广告变现数据！**
> **注意**
> **抖音小游戏、快手小游戏、B 站小游戏无需接入，会由引力后端自动拉取，具体配置，请参考**[这里](https://gravityengine.feishu.cn/wiki/SBsxwmeb5iNrPKkUtzCcmisXnzd#OwM8doB35oKDTrxsHKkcvr9Bnqe)
若您的产品内有广告变现，则需要在用户点击广告观看的同时上报用户广告观看事件给引力，具体参考如下：
#### 方法示例 [#方法示例-1]
**Android/iOS**
```csharp
public static void TrackNativeAppAdShowEvent(string adUnionType, string adPlacementId, string adSourceId, string adType, string adnType, float ecpm)
```
为生成准确的广告收益分析报表，请尽量遵循规范填写下方的广告平台参数。正确的字段是生成有价值报表的基础。
我们为您准备了详细的指引： 👉 [广告聚合平台字段配置说明](/docs/appendix/ad-mediation-fields)
| **参数名称** | **参数含义** | **参数类型** | **是否必传** |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------ | -------- | -------- |
| adUnionType | 广告聚合平台类型（取值为：topon、gromore、admore、self，分别对应Topon、Gromore、Admore、自建聚合） | string | 否 |
| adPlacementId | 广告瀑布流ID（广告位ID） | string | 否 |
| adSourceId | 广告源ID（代码位ID） | string | 否 |
| adType | 广告类型 （取值为：reward(激励视频广告)、banner(横幅广告)、 native(信息流广告)、interstitial(插屏广告)、 splash(开屏广告) 、video\_feed(视频信息流)、 video\_begin(贴片广告)） | string | 是 |
| adnType | 广告平台类型（取值为：csj、gdt、ks、 mint 、baidu，分别对应为穿山甲、优量汇、快手联盟、Mintegral、百度联盟） | string | 否 |
| ecpm | 预估ECPM价格（千次展示收入（单位元）） | float | 建议填写 |
**小游戏/快游戏**
```csharp
public static void TrackMiniGameAdShowEvent(string adType, string adUnitId, Dictionary otherProperties = null)
```
为生成准确的广告收益分析报表，请尽量遵循规范填写下方的广告平台参数。正确的字段是生成有价值报表的基础。
我们为您准备了详细的指引： 👉 [广告聚合平台字段配置说明](/docs/appendix/ad-mediation-fields)
| **参数名称** | **参数含义** | **参数类型** | **是否必传** |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- | -------- |
| adType | 广告类型 （取值为：reward、banner、native、interstitial、video\_feed、video\_begin，分别对应激励视频广告、Banner广告、原生模板广告、插屏广告、视频广告、视频贴片广告） | string | 是 |
| adUnitId | 广告位ID（一般以adunit开头，注意不要填错，会导致广告收入统计不准！） | string | 是 |
| otherProperties | 自定义参数。其他需要携带的自定义参数，需要提前在引力后台[元数据管理](https://web.gravity-engine.com/#/manage/metadata/eventProperty)中针对广告观看($AdShow) 事件配置好相关属性，比如快游戏上报广告 ecpm，可以使用引力预置好的属性字段：$ecpm，具体见下方代码示例。 | Dictionary\ | 否 |
#### 调用示例 [#调用示例-2]
**Android/iOS**
```csharp
GravityEngineAPI.TrackNativeAppAdShowEvent("topon", "placement_id", "ad_source_id", "reward", "csj", 1);
```
**小游戏/快游戏**
```csharp
var otherProperties = new Dictionary()
{
{"$ecpm", 10000}, // 本次广告曝光的 ECPM
{"other_key", "other_value"} // 其他想携带的属性信息
};
GravityEngineAPI.TrackMiniGameAdShowEvent("reward", "your_ad_unit_id", otherProperties);
```
## 5. 接入验证 [#5-接入验证]
> **注意**
> **正式上线之前，请完成本节的校验，否则可能会导致买量上报异常！**
### 5.1 关键事件验证 [#51-关键事件验证]
在引力后台[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow) 界面开启**加载实时数据**，并在产品中触发以下几个事件。事件验收与排错：[接入验收与排错](/docs/getting-started/integration-checklist)
| 事件名 | 事件英文名 | 触发时机 | 采集方式 | 默认映射到媒体事件 | 备注 |
| ---- | ----------------------------------------- | ---------- | ---------------------- | --------- | ----------------------- |
| 用户注册 | APP:`$AppRegister`
小游戏:`$MPRegister` | 用户完成业务注册之后 | 调用SDK的**上报业务注册事件**方法采集 | 暂无 | 接入了**业务注册上报事件**的产品均需要校验 |
| 付费 | `$PayEvent` | 用户付费之后 | 调用SDK的**上报用户付费事件**方法采集 | 付费 | 接入了**付费事件上报事件**的产品均需要校验 |
| 广告展示 | `$AdShow` | 用户观看广告之后 | 调用SDK的**上报广告展示事件**方法采集 | 暂无 | 接入了**广告事件上报事件**的产品均需要校验 |
| 用户提现 | `$UserWithdraw` | 用户提现之后 | 调用SDK的**上报用户提现事件**方法采集 | 暂无 | 接入了**用户提现上报事件**的产品均需要校验 |
触发操作后，请在[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow) 界面中筛选测试用户的 Client ID，观察对应事件是否出现在实时入库页面。若事件数据正常显示，则说明接入成功；如出现于错误数据页面请根据页面错误提示进行排查；如未显示对应数据，请及时联系引力运营支持团队获取协助。
### 5.2 避免重复上报 [#52-避免重复上报]
如果您之前单独接了媒体的回传(SDK 或者 API)，则上线之前需要去掉，否则可能会导致重复上报数据！
> **注意**
> 至此验证无误之后，您可以正常上线了。
## 6. 媒体平台SDK集成说明 [#6-媒体平台sdk集成说明]
**🎯 集成策略说明：**
Unity SDK **仅针对【微信小游戏】平台** 集成了腾讯广告小游戏SDK。对于Unity项目发布至其他平台（如抖音小游戏、Android App、iOS App等），**我们未集成任何媒体的SDK**。
### 6.1 微信小游戏平台 [#61-微信小游戏平台]
* **状态**：已集成腾讯广告小游戏SDK
* **上报方式**：需**手动调用**我们提供的方法进行事件上报
* **版本**：自 `4.8.34`开始支持
> **重要说明**
> 按照《腾讯广告小游戏 SDK 集成》的步骤完成集成后，引力SDK会**自动上报**以下两个基础事件给腾讯：
>
> * REGISTER（用户注册）
> * RE\_ACTIVE（沉默唤起）
>
> 此外，**START\_APP**（小游戏启动）事件由腾讯SDK**自动采集**（引力SDK初始化腾讯SDK时默认开启该功能）。
>
> 除以上事件外，其他所有事件（如付费、自定义行为等）均需**客户端手动调用**我们提供的方法进行上报。
>
> 点击查看详细集成文档：[腾讯广告小游戏 SDK 集成](/docs/client-sdk/unity/advanced/tencent-ads-integration)
### 6.2 其他平台 [#62-其他平台]
*(包括但不限于：抖音小游戏、OPPO小游戏、vivo小游戏、Android App、iOS App等)*
* **状态**：**未集成**任何媒体SDK（腾讯、巨量等均未集成）
* **上报方式**：如需向媒体平台上报事件，请**自行接入**该平台的官方SDK