快速集成

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

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

媒体平台SDK集成说明

🎯 集成策略说明：

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

1. 微信小游戏平台 ✅

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

📌 重要说明

按照《引力&腾讯广告小游戏 SDK 接入指南（Unity C#版）》的步骤完成集成后，引力SDK会自动上报以下两个基础事件给腾讯：

• REGISTER（用户注册）
• RE_ACTIVE（沉默唤起）

此外，START_APP（小游戏启动）事件由腾讯SDK自动采集（引力SDK初始化腾讯SDK时默认开启该功能）。

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

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

2. 其他平台 ❌

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

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

1. SDK 基础配置

微信小游戏：需要先参考微信团队发布的微信小游戏适配方案。

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

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

1.1 接入步骤

1.1.1 导入UnityPackage

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

下载最新的 GravityEngine.unitypackage，通过 Assets > Import Package > Custom Package导入。---

1.1.2 SDK配置

国内：默认为国内。如需切换，可在unity菜单->引力引擎->使用国内SDK进行切换**海外：**导入unitypackage后，unity菜单->引力引擎->使用海外SDK

1.1.3 插件自动集成

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

导入后包含以下关键文件夹：

📁 Assets/ExternalDependencyManager

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

📁 Assets/GravityNet

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

1.1.4 手动集成

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

1.1.5 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.3 Harmony配置

• 鸿蒙只支持国内，unity必须使用unity国内版 《团结引擎》
• 鸿蒙底层SDK，需要手动集成SDK
  1. 方式一：集成方式参考HarmonyOS接入文档 第一步下载安装
  2. 方式二：下载鸿蒙底层har包，放到/Assets/Plugins/OpenHarmony/gravityengine.har目录下
• TuanjiePlayerAbilityBase 类里，onCreate方法（可选，仅支持接入方式一，如果需要元服务App Linking跟踪（want.parameters）需设置）

import { GravityEngineUnityChannel } from '../GravityEngineUnityChannel';

export class TuanjiePlayerAbilityBase extends UIAbility {
    onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
        GravityEngineUnityChannel.onUnityAppStart(this.context,want.parameters);
    }
}

1.4 添加全局宏参数

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

支持平台	宏参数	备注
微信小游戏	GRAVITY_WECHAT_GAME_MODE
抖音小游戏	GRAVITY_BYTEDANCE_GAME_MODE
抖音小游戏 TT SDK 模式/Tiktok	GRAVITY_BYTEDANCE_TT_GAME_MODE	如您已升级到 TT SDK，使用本模式，详情请参考抖小 SDK 官方文档
抖音云游戏	GRAVITY_BYTEDANCE_CLOUD_MODE
快手小游戏	GRAVITY_KUAISHOU_GAME_MODE
快手小游戏 WEBGL	GRAVITY_KUAISHOU_WEBGL_GAME_MODE	如果使用的老版本webGLSDK，请添加宏 KUAISHOU_WEBGL_BELOW_TUANJIE_VERSION 建议更新到最新版本的快手webGLSDK 更新参考：快手官方文档
支付宝小游戏	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	其他修改请参考这篇文档
小米快游戏	GRAVITY_XIAOMI_GAME_MODE	其他修改请参考这篇文档
VIVO快游戏	GRAVITY_VIVO_GAME_MODE
Android	无需配置宏参数
iOS	无需配置宏参数
Harmony	无需配置宏参数
Windows	无需配置宏参数

1. 手动添加，添加步骤如下：

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

2. 通过可视化界面添加

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

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域名到合法域名列表中，否则将导致事件采集失效，影响您的使用！

// 手动初始化（动态挂载 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<string, object>()
{
  {"testSuperKey", "testSuperValue"}
};

//Android设备clientID优先级顺序，默认优先取 OAID 为clientId
token.mClientIdPriorityOrder = new List<GravityEngineAPI.AndroidClientIdType>(){
GravityEngineAPI.AndroidClientIdType.OAID, GravityEngineAPI.AndroidClientIdType.ANDROID_ID};

// 启动引力引擎
GravityEngineAPI.StartGravityEngine(token);

非通用启动方法

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

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

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>    是否开启同步获取归因信息，在媒体点击下发延迟的情况下会影响归因，请谨慎开启。具体请参考同步归因：/docs/attribution/synchronous-attribution
/// <param name="initializeCallback"></param>       网络回调，其他方法均需在回调成功之后才可正常使用
/// <exception cref="ArgumentException"></exception>
GravityEngineAPI.Initialize("your_user_client_id", "name_123", 1, "your_openid_111", false, new InitializeCallbackImpl());

4. 事件上报

4.1 业务注册事件上报

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

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

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

调用示例

GravityEngineAPI.TrackAppRegister();

4.2 付费事件上报

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

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

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

方法示例

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

参数说明

返回值

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

调用示例

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

4.3 广告观看事件上报

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

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

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

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

方法示例

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

调用示例

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

5. 接入验证

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

5.1 关键事件验证

在引力后台事件流 界面开启加载实时数据，并在产品中触发以下几个事件。事件流使用说明：事件流 - 飞书云文档

触发操作后，请在事件流 界面中筛选测试用户的 Client ID，观察对应事件是否出现在实时入库页面。若事件数据正常显示，则说明接入成功；如出现于错误数据页面请根据页面错误提示进行排查；如未显示对应数据，请及时联系引力运营支持团队获取协助。

5.2 避免重复上报

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

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