快速集成

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

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

1. SDK 基础配置

1.1 接入步骤

1.1.1 导入UnityPackage

使用低版本(5.0.24及之前)插件的客户, 要升级到5.0.25(或以上版本)，可参考UnitySDK 升级方案

1.1.2. 插件自动集成

详细操作请参考：《EDM4U插件使用说明》文档

📁 Assets/ExternalDependencyManager

• ​​作用​​：EDM4U插件（用于自动依赖管理）
• ​​处理​​：如果项目已使用该插件，导入时可跳过此文件夹

📁 Assets/GravityNet

• ​​作用​​：EDM4U插件自动接入底层SDK的配置
• ​​处理​​：如果明确不需要EDM4U插件方式，可不导入此文件夹，但需要参照iOS和Android的接入文档手动导入底层SDK
• 特殊情况：使用EDM4U插件自动接入失败（如unity版本不支持该插件,iOS没有cocoapods环境等），也需要参照参照iOS和Android的接入文档手动导入底层SDK。

1.1.3 手动集成

参考UnitySDK 升级方案 里的非插件引入方式

1.1.4. SDK冲突说明

如果原工程已经接入了华为或荣耀SDK，导致接入我们SDK后出现编译失败，可以编辑Assets/GravityNet/GravityPlugins/Oaid/Editor/Dependencies.xml文件，移除对应冲突的SDK

 

1.2 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.5 添加全局宏参数

正式接入之前，您需要针对不同的平台添加不同的全局宏参数，目前引力 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>(){});

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、应用宝
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 );

// 手动初始化（动态挂载 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.初始化

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

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());

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());

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

// Android/iOS
GravityEngineAPI.TrackAppRegister();

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

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

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

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

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);