本文档主要讲述 Android 原生包接入引力引擎的技术接入方案，在开始接入前，建议您先阅读接入前准备以了解接入必备的基础概念。

📌 重要说明

Android SDK未集成任何媒体SDK（如巨量引擎、腾讯广告等）。如您需要在Android端上报事件给媒体平台，请：

自行集成所需媒体的官方SDK

按照各媒体的文档要求进行事件上报

1. 获取 AccessToken

您可以在设置-应用管理页面点击查看参数按钮获取当前应用的 AccessToken ，请妥善保存避免泄露。

2. 集成 SDK

2.1 自动集成(推荐)

在 Project 级别的 build.gradle 文件中添加如下配置依赖：

maven { url 'https://nexus.gravity-engine.com/repository/maven-releases/' }
maven { url 'https://nexus.gravity-engine.com/repository/maven-snapshots/' }
maven { url 'https://developer.huawei.com/repo' }
maven { url 'https://developer.hihonor.com/repo' }

Module 工程目录下的 build.gradle 文件中添加依赖项：

implementation ("cn.gravity.android:GravityEngineSDK:${LATEST_VERSION}")
// 添加依赖
implementation "com.huawei.hms:ads-identifier:3.4.62.300"//华为SDK
implementation 'com.hihonor.mcs:ads-identifier:1.0.3.300'//荣耀SDK

如果您集成SDK后编译时【出现】类似 com.hihonor.ads.identifier.AdvertisingIdClient$Info is defined multiple times的错误，请根据实际情况处理：

如果是荣耀设备出现的冲突，请在依赖配置中去掉华为SDK的implementation

如果是华为设备出现的冲突，请在依赖配置中去掉荣耀SDK的implementation

如果同时存在两个库的冲突，请在依赖配置中去掉华为和荣耀SDK的implementation

${LATEST_VERSION} 请参见发版记录请使用其中最新版本的 version 以保证获得引力及时的更新支持。

2.2 手动集成

下载并解压最新 Android SDK 包，您可以在SDK下载下载最新版本 SDK aar 包
在项目 libs 文件夹中添加 GravityEngineSDK.aar
在 Project 级别的 build.gradle 文件中添加如下配置依赖：

// 添加 repo 地址
maven { url 'https://developer.huawei.com/repo' }
maven { url 'https://developer.hihonor.com/repo' }

在 Module 工程目录下的 build.gradle 添加如下配置引入依赖

dependencies {
    implementation fileTree(dir: 'libs', include: ['*.jar','*.aar'])
    // 添加依赖
    implementation "com.huawei.hms:ads-identifier:3.4.62.300"//华为SDK
    implementation "com.hihonor.mcs:ads-identifier:1.0.3.300"//荣耀SDK
}

如果您集成SDK后编译时【出现】类似 com.hihonor.ads.identifier.AdvertisingIdClient$Info is defined multiple times的错误，请根据实际情况处理：

如果是荣耀设备出现的冲突，请在依赖配置中去掉华为SDK的implementation

如果是华为设备出现的冲突，请在依赖配置中去掉荣耀SDK的implementation

如果同时存在两个库的冲突，请在依赖配置中去掉华为和荣耀SDK的implementation

3. 配置并启动 SDK

// 在主线程中配置并启动SDK
GEConfig config = GEConfig.getInstance(context, ACCESS_TOKEN);
config.enableAndroidId(true); // 传入 false，则表示关闭 Androidid采集，非必须不要关闭，会影响归因率！5.0.9 及以上版本支持
config.enableOAID(true); // 传入 false，则表示关闭 OAID采集，非必须不要关闭，会影响归因率！5.0.9 及以上版本支持
config.enableIMEI(true); // 传入 false，则表示关闭 IMEI 采集，非必须不要关闭，会影响归因率！5.0.9 及以上版本支持
config.enableMAC(true); // 传入 false，则表示关闭 mac采集，非必须不要关闭，会影响归因率！5.0.16及以上版本支持
// 保存此实例，后续调用方法均需要用到
GravityEngineSDK gravityEngineSDKInstance = GravityEngineSDK.setupAndStart(config);

参数说明：

ACCESS_TOKEN : 在第一步中获取的项目通行证 AccessToken

应用每次启动都要执行 SDK 的启动逻辑，建议在用户同意隐私政策弹窗之后尽早调用。

4. 初始化

在用户可以获取到用户唯一性 ID 时调用此方法，推荐首次安装启动时调用，请启动应用之后尽早调用。

首次调用后，需要等 InitializeCallback 回调的 onSuccess 回调成功之后才能继续调用其他事件上报的方法

初始化方法调用成功之后，后续冷启动可以不再调用，只需要正常启动 SDK 即可（多次调用也不会有问题，引力做了兼容）

gravityEngineSDKInstance.initialize(ACCESS_TOKEN, USER_CLIENT_ID, USER_CLIENT_NAME, CHANNEL, new InitializeCallback() {
    @Override
    public void onFailed(String errorMsg, JSONObject initializeBody) {
        Log.d(TAG, "initialize failed " + errorMsg);
    }

    @Override
    public void onSuccess(JSONObject responseJson, JSONObject initializeBody) {
        Log.d(TAG, "initialize success");
    }
}, ENABLE_SYNC_ATTRIBUTION);

参数说明：

参数名称	参数含义	参数类型	是否必传
ACCESS_TOKEN	项目通行证，同启动 SDK 时保持一致	string	是
USER_CLIENT_ID	用户唯一 ID(例如 UID 或者设备 ID)。（需SDK版本大于5.0.9）如果传空，则引力 sdk 内部会自动采集设备 id 填入，采集优先级顺序为：oaid > android_id > imei，如果所有id 都采集不到时，会生成随机的 16 位 id 保存到本地缓存中以保持相对稳定	string	否
USER_CLIENT_NAME	用户昵称，如果传空，则引力 sdk 内部会自动根据 client_id 计算 md5 生成	string	否
CHANNEL	用户初始化渠道(例如 xiaomi、huawei 等)	string	是
ENABLE_SYNC_ATTRIBUTION	是否开启同步获取归因信息，具体请参考同步归因	boolean	是

5.事件上报

5.1 业务注册事件上报

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

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

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

方法示例

public String trackRegisterEvent()

返回值

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

调用示例

gravityEngineSDKInstance.trackRegisterEvent();

5.2 付费事件上报

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

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

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

方法示例

public 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

调用示例

gravityEngineSDKInstance.trackPayEvent(300, "CNY", "order_id" + System.currentTimeMillis(), "月卡", "支付宝");

5.3 广告观看事件上报

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

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

方法示例

public String trackAdShowEvent(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、other，分别对应为穿山甲、优量汇、快手联盟、Mintegral、百度联盟、其他平台）	string	否
ecpm	预估ECPM价格（千次展示收入（单位元））请务必注意，做好单位转换，传错单位可能会导致买量受到影响！	float	建议填写

返回值

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

调用示例

// 上报广告观看事件
gravityEngineSDKInstance.trackAdShowEvent("topon", "placement_id", "ad_source_id", "reward", "csj", 1);

5.4 提现事件上报

提现事件仅与涉及用户提现功能的平台相关，如无此类业务需求，则无需接入此事件。

当用户发生应用内提现行为时，需要调用 trackWithdrawEvent 方法记录用户提现事件！

方法示例

public String trackWithdrawEvent(int payAmount, String payType, String orderId, String payReason, String payMethod)

参数说明

参数名称	参数含义	参数类型	是否必传
payAmount	提现金额单位为分	int	是
payType	货币类型按照国际标准组织ISO 4217中规范的3位字母，例如CNY人民币、USD美金等国际标准组织 ISO 4217 代码表	string	是
orderId	订单号。引力引擎会通过订单号 `orderId` 去重，避免重复上报，请务必传入！	string	是
payReason	提现原因例如：用户首次提现、用户抽奖提现	string	是
payMethod	提现支付方式例如：支付宝、微信、银联等	string	是

返回值

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

调用示例

gravityEngineSDKInstance.trackWithdrawEvent(300, "CNY", "order_id" + System.currentTimeMillis(), "用户首次提现", "支付宝");

6.接入验证

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

6.1 关键事件验证

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

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

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

6.2 避免重复上报

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

至此验证无误之后，技术接入工作完成，您可以转交发行买量团队继续推动后续流程～