本文档主要讲述 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}"){
    exclude group: 'com.huawei.hms', module: 'ads-identifier'
    exclude group: 'com.hihonor.mcs', module: 'ads-identifier'
}

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

2.2 手动集成(不推荐使用)

请注意：我们强烈建议您【不要】使用手动集成的方案，因为引力 aar 包中依赖了华为和荣耀的官方包用以获取 oaid，使用手动集成很容易造成这些包依赖失败，并且需要处理和其他 aar 包的冲突问题！

下载并解压最新 Android SDK 包，您可以在SDK下载下载最新版本 SDK aar 包
在项目 libs 文件夹中添加 GravityEngineSDK.aar
在 Module 工程目录下的 build.gradle 添加如下配置引入依赖

dependencies {
    implementation fileTree(dir: 'libs', include: ['*.jar','*.aar'])
}

如果您需要安装华为和荣耀的包，需要添加如下代码：
maven { url 'https://developer.huawei.com/repo' }
maven { url 'https://developer.hihonor.com/repo' }
如果您需要解决和其他 aar 包的冲突问题，需要在引用引力 aar 包的时候，添加如下代码：
{
    exclude group: 'com.huawei.hms', module: 'ads-identifier'
    exclude group: 'com.hihonor.mcs', module: 'ads-identifier'
}

3. 配置并启动 SDK

// 在主线程中配置并启动SDK
GEConfig config = GEConfig.getInstance(context, ACCESS_TOKEN);
// 保存此实例，后续调用方法均需要用到
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 开启 Debug 模式

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

Normal: 线上模式，数据会存入缓存，并依据一定的缓存策略上报
Debug: 测试模式，数据逐条上报。当出现问题时会以日志和异常的方式提示用户，您也可以去事件流中查看实时上报的数据数，辅助您判断数据接入是否正常。

您可以通过如下方式来开启 Debug

GEConfig config = GEConfig.getInstance(mContext, Constants.ACCESS_TOKEN);
config.setMode(GEConfig.ModeEnum.DEBUG);

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

6.2 关键事件验证

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

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

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

6.3 避免重复上报

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

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