# 快速集成
> 来源：https://help.gravity-engine.com/docs/client-sdk/android/quickstart
> 介绍 Gravity Engine Android SDK 的安装、初始化、用户注册与事件上报流程，并提供参数说明和调用示例。
本文档主要讲述 **Android** 原生包接入 [引力引擎](https://gravity-engine.com/) 的技术接入方案，在开始接入前，建议您先阅读 [接入前准备](/docs/getting-started/overview)以了解接入必备的基础概念。
> 📌 **重要说明**
>
> Android SDK**未集成任何媒体SDK**（如巨量引擎、腾讯广告等）。如您需要在Android端上报事件给媒体平台，请：
>
> 1. **自行集成**所需媒体的官方SDK
> 2. 按照各媒体的文档要求进行事件上报
## 1. 获取 AccessToken [#1-获取-accesstoken]
您可以在[设置-应用管理](https://web.gravity-engine.com/#/manage/appmanage)页面点击 查看参数 按钮获取当前应用的 AccessToken ，请妥善保存避免泄露。
## 2. 集成 SDK [#2-集成-sdk]
### 2.1 自动集成(推荐) [#21-自动集成推荐]
* 在 `Project` 级别的 `build.gradle` 文件中添加如下配置依赖：
```groovy
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` 文件中添加依赖项，按您的发行地区选择：
```groovy
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
```
```groovy
implementation ("oversea.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
//海外需额外添加依赖
implementation "com.android.installreferrer:installreferrer:+"//Google
```
> 如果您集成SDK后编译时**出现**类似 `com.hihonor.ads.identifier.AdvertisingIdClient$Info is defined multiple times`的错误，请根据实际情况处理：
>
> 1. 如果是**荣耀设备**出现的冲突，请在依赖配置中去掉荣耀SDK的implementation
> 2. 如果是**华为设备**出现的冲突，请在依赖配置中去掉华为SDK的implementation
> 3. 如果同时存在两个库的冲突，请在依赖配置中去掉华为和荣耀SDK的implementation
> `${LATEST_VERSION}` 请参见[发版记录](/docs/client-sdk/android/changelog) 请使用其中最新版本的 version 以保证获得引力及时的更新支持。
### 2.2 手动集成 [#22-手动集成]
* 下载并解压最新 Android SDK 包，您可以在[SDK下载](/docs/client-sdk/sdk-overview)下载最新版本 SDK aar 包
* 在项目 `libs` 文件夹中添加 `GravityEngineSDK.aar`
* 在 `Project` 级别的 `build.gradle` 文件中添加如下配置依赖：
```groovy
// 添加 repo 地址
maven { url 'https://developer.huawei.com/repo' }
maven { url 'https://developer.hihonor.com/repo' }
```
* 在 `Module` 工程目录下的 `build.gradle` 添加如下配置引入依赖
```groovy
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
// 海外需额外添加依赖
implementation "com.android.installreferrer:installreferrer:+"//Google
}
```
> 如果您集成SDK后编译时**出现**类似 `com.hihonor.ads.identifier.AdvertisingIdClient$Info is defined multiple times`的错误，请根据实际情况处理：
>
> 1. 如果是**荣耀设备**出现的冲突，请在依赖配置中去掉荣耀SDK的implementation
> 2. 如果是**华为设备**出现的冲突，请在依赖配置中去掉华为SDK的implementation
> 3. 如果同时存在两个库的冲突，请在依赖配置中去掉华为和荣耀SDK的implementation
## 3. 配置并启动 SDK [#3-配置并启动-sdk]
> 应用每次启动都要执行 `SDK` 的启动逻辑，建议在用户同意隐私政策弹窗之后尽早调用。
```java
// 在主线程中配置并启动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及以上版本支持
//设置clientID生成顺序。默认OAID第一，Android_ID第二，其他遵循SDK自动生成顺序。5.0.22及以上版本支持
config.setClientIdPriorityOrder(new ArrayList<>(Arrays.asList(GEConfig.ClientIdType.CLIENTID_OAID,GEConfig.ClientIdType.CLIENTID_ANDROID_ID )));
//预设公共属性
JSONObject superProperties = new JSONObject();
superProperties.put("testSuperKey","testSuperValue");
config.setPresetSuperProperties(superProperties);
// 保存此实例，后续调用方法均需要用到
GravityEngineSDK gravityEngineSDKInstance = GravityEngineSDK.setupAndStart(config);
```
```java
// 在主线程中配置并启动SDK
GEConfig config = GEConfig.getInstance(context, ACCESS_TOKEN);
config.isGDPRArea(false); //是否欧盟地区 选调，默认false 如果你的应用在欧盟地区运营，则需要符合欧盟隐私保护法律的规定（关于GDPR），请务必在用户拒绝采集设备敏感信息时设置 isGDPRArea(true) 5.0.21 及以上版本支持
config.setCoppaEnabled(false); //是否需要符合《儿童在线隐私权保护法》 选调，默认false 如果您的应用需要符合《儿童在线隐私权保护法》(COPPA) 规定，设置 setCoppaEnabled = true 5.0.21 及以上版本支持
config.setKidsAppEnabled(false); //是否儿童应用 选调，默认false 如果您的应用会定向到不满 13 周岁的儿童，则需要将其标记为儿童应用 (Kids App)，设置 setKidsAppEnabled = true 5.0.21 及以上版本支持
config.setFbAppID(""); //应用Facebook appId 选调，默认"" 如果您的应用需要进行Facebook归因，请设置你的FacebookID 5.0.21及以上版本支持
config.adPersonalizationEnabled(false); //户是否允许Google将其数据用于个性化广告的意见结果 选调，默认false 如果你的应用在欧盟地区运营并且在Google投放您的应用，请务必将用户是否允许Google将其数据用于个性化广告的意见结果传入该属性，以确保您符合Google对欧盟用户意见征求政策的新政策 5.0.21 及以上版本支持
config.adUserDataEnabled(false); //用户是否同意将其数据发送到Google的意见结果 选调，默认false 如果你的应用在欧盟地区运营并且在Google投放您的应用，请务必将用户是否同意将其数据发送到Google的意见结果传入该属性，以确保您符合Google对欧盟用户意见征求政策的新政策 5.0.21 及以上版本支持
// 保存此实例，后续调用方法均需要用到
GravityEngineSDK gravityEngineSDKInstance = GravityEngineSDK.setupAndStart(config);
```
参数说明：
* `ACCESS_TOKEN` : 在第一步中获取的项目通行证 AccessToken
## 4. 初始化 [#4-初始化]
在用户可以获取到用户唯一性 `ID` 时调用此方法，推荐首次安装启动时调用，请启动应用之后尽早调用。
> 首次调用后，需要等 `InitializeCallback` 回调的 `onSuccess` **回调成功之后才能继续调用其他事件上报的方法**
>
> 初始化方法调用成功之后，后续冷启动可以不再调用，只需要正常启动 SDK 即可（多次调用也不会有问题，引力做了兼容）
```java
JSONObject adData = new JSONObject();
adData.put("testAdKey","testAdValue");
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, adData);
```
参数说明：
| 参数名称 | 参数含义 | 参数类型 | 是否必传 |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ---- |
| 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 | 是否开启同步获取归因信息，具体请参考[同步归因](/docs/attribution/synchronous-attribution) | boolean | 是 |
| adData | 预设归因信息 | object | 否 |
## 5. 事件上报 [#5-事件上报]
### 5.1 业务注册事件上报 [#51-业务注册事件上报]
> **如果您的应用不需要追踪用户注册行为，可以跳过此事件接入。此功能仅适用于需要统计业务注册转化数据的场景。**
> 该方法可多次调用，每次调用都会上报一个用户注册事件（计算指标时会去重）
当用户完成应用内业务注册后，您可以调用 `trackRegisterEvent` 方法来上报用户注册事件(`$AppRegister`)给引力，引力会使用该事件统计后台计算指标：标准\_注册数
#### 方法示例 [#方法示例]
```java
public String trackRegisterEvent()
```
#### 返回值 [#返回值]
返回值为当前事件生成的事件 trace\_id
#### 调用示例 [#调用示例]
```java
gravityEngineSDKInstance.trackRegisterEvent();
```
### 5.2 付费事件上报 [#52-付费事件上报]
> **付费事件上报用于收入统计和分析，如您的应用不涉及内购或付费服务，则无需接入此事件。**
> 如果您需要通过后端 API 方式上报付费事件，请参考 [混合上报模式](/docs/client-sdk/hybrid-reporting) 来接入事件上报接口报送付费事件。
当用户发生付费行为时，需要调用 `trackPayEvent` 方法记录用户付费事件，此事件非常重要，会影响买量和 ROI 统计，请务必重点测试！
#### 方法示例 [#方法示例-1]
```java
public 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 | 是 |
#### 返回值 [#返回值-1]
返回值为当前事件生成的事件 trace\_id
#### 调用示例 [#调用示例-1]
```java
gravityEngineSDKInstance.trackPayEvent(300, "CNY", "order_id" + System.currentTimeMillis(), "月卡", "支付宝");
```
### 5.3 广告观看事件上报 [#53-广告观看事件上报]
> **广告观看上报适用于广告变现类应用，若您的应用未集成广告模块，则无需接入此事件。**
若您的产品内有广告变现，则需要在用户点击广告观看的同时上报用户广告观看事件给引力，具体参考如下：
#### 方法示例 [#方法示例-2]
```java
public String trackAdShowEvent(String adUnionType, String adPlacementId, String adSourceId, String adType, String adnType, float ecpm)
```
#### 参数说明 [#参数说明-1]
为生成准确的广告收益分析报表，请尽量遵循规范填写下方的广告平台参数。正确的字段是生成有价值报表的基础。
我们为您准备了详细的指引： 👉 [广告聚合平台字段配置说明](/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、other，分别对应为穿山甲、优量汇、快手联盟、Mintegral、百度联盟、其他平台） | string | 否 |
| ecpm | 预估ECPM价格（千次展示收入（单位元）） 请务必注意，做好单位转换，传错单位可能会导致买量受到影响！ | float | 建议填写 |
#### 返回值 [#返回值-2]
返回值为当前事件生成的事件 trace\_id
#### 调用示例 [#调用示例-2]
```java
// 上报广告观看事件
gravityEngineSDKInstance.trackAdShowEvent("topon", "placement_id", "ad_source_id", "reward", "csj", 1);
```
### 5.4 提现事件上报 [#54-提现事件上报]
> **提现事件仅与涉及用户提现功能的平台相关，如无此类业务需求，则无需接入此事件。**
当用户发生应用内提现行为时，需要调用 `trackWithdrawEvent` 方法记录用户提现事件！
#### 方法示例 [#方法示例-3]
```java
public String trackWithdrawEvent(int payAmount, String payType, String orderId, String payReason, String payMethod)
```
#### 参数说明 [#参数说明-2]
| 参数名称 | 参数含义 | 参数类型 | 是否必传 |
| --------- | ------------------------------------------------------------------------------------------------------------- | ------ | ---- |
| payAmount | 提现金额 单位为分 | int | 是 |
| payType | 货币类型 按照国际标准组织ISO 4217中规范的3位字母，例如CNY人民币、USD美金等 [国际标准组织 ISO 4217 代码表](https://en.wikipedia.org/wiki/ISO_4217) | string | 是 |
| orderId | 订单号。引力引擎会通过订单号 `orderId` 去重，避免重复上报，请务必传入！ | string | 是 |
| payReason | 提现原因 例如：用户首次提现、用户抽奖提现 | string | 是 |
| payMethod | 提现支付方式 例如：支付宝、微信、银联等 | string | 是 |
#### 返回值 [#返回值-3]
返回值为当前事件生成的事件 trace\_id
#### 调用示例 [#调用示例-3]
```java
gravityEngineSDKInstance.trackWithdrawEvent(300, "CNY", "order_id" + System.currentTimeMillis(), "用户首次提现", "支付宝");
```
## 6. 接入验证 [#6-接入验证]
> **正式上线之前，请完成本节的校验，否则可能会导致买量上报异常！**
### 6.1 关键事件验证 [#61-关键事件验证]
在引力后台[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow) 界面开启**加载实时数据**，并在产品中触发以下几个事件。事件流使用说明：[事件流 - 飞书云文档](https://gravityengine.feishu.cn/wiki/ZFmYwiDxfiZe2lkt3occ6yBonpf)
| 事件名 | 事件英文名 | 触发时机 | 采集方式 | 默认映射到媒体事件 | 备注 |
| ---- | --------------- | ---------- | ----------------------- | --------- | ----------------------- |
| 用户注册 | `$AppRegister` | 用户完成业务注册之后 | 调用SDK的**上报业务注册事件**方法采集 | 暂无 | 接入了**业务注册上报事件**的产品均需要校验 |
| 付费 | `$PayEvent` | 用户付费之后 | 调用SDK的**上报用户付费事件**方法采集 | 付费 | 接入了**付费事件上报事件**的产品均需要校验 |
| 广告展示 | `$AdShow` | 用户观看广告之后 | 调用SDK的**上报广告展示事件**方法采集 | 暂无 | 接入了**广告事件上报事件**的产品均需要校验 |
| 用户提现 | `$UserWithdraw` | 用户提现之后 | 调用SDK的**上报用户提现事件** 方法采集 | 暂无 | 接入了**用户提现上报事件**的产品均需要校验 |
触发操作后，请在[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow) 界面中筛选测试用户的 Client ID，观察对应事件是否出现在实时入库页面。若事件数据正常显示，则说明接入成功；如出现于错误数据页面请根据页面错误提示进行排查；如未显示对应数据，请及时联系引力运营支持团队获取协助。
### 6.2 避免重复上报 [#62-避免重复上报]
如果您之前单独接了媒体的回传(SDK 或者 API)，则上线之前需要去掉，否则可能会导致重复上报数据！
> 至此验证无误之后，技术接入工作完成，您可以转交发行买量团队继续推动后续流程～