快速接入
本文档为Android接入 引力引擎 4.x 版本 的技术接入方案,详细使用请参考 Demo 工程。
提示
在接入前, 请先阅读 接入前准备
注意
在正式上线之前,请参考 接入验证 完成接入校验。
1. 集成引力引擎 SDK
1.1 自动集成
- 在
Project
级别的build.gradle
文件中添加如下配置依赖:
maven {
url 'https://nexus.gravity-engine.com/repository/maven-releases/'
}
maven {
url 'https://nexus.gravity-engine.com/repository/maven-snapshots/'
}
Module
工程目录下的build.gradle
文件中添加依赖项:
implementation "cn.gravity.android:GravityEngineSDK:${LATEST_VERSION}"
提示
${LATEST_VERSION}
请参见发版记录。
1.2 手动集成
- 下载并解压 最新 Android SDK
- 在项目
libs
文件夹中添加GravityEngineSDK.aar
- 在
Module
工程目录下的build.gradle
添加如下配置引入依赖
dependencies {
implementation fileTree(dir: 'libs', include: ['*.jar','*.aar'])
}
2. 配置并启动 SDK
// 在主线程中配置并启动SDK
GEConfig config = GEConfig.getInstance(context, ACCESS_TOKEN);
// 保存此实例,后续调用方法均需要用到
GravityEngineSDK gravityEngineSDKInstance = GravityEngineSDK.setupAndStart(config);
参数说明:
ACCESS_TOKEN
: 项目通行证:在应用列表中找到
注意
应用每次启动都要执行 SDK
的启动逻辑,建议在用户同意隐私政策弹窗之后尽早调用。
3. 常用功能
3.1 初始化
在用户可以获取到用户唯一性 ID
时调用此方法,推荐首次安装启动时调用。
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 时保持一致USER_CLIENT_ID
: 用户唯一 ID(例如 UID 或者设备 ID)USER_CLIENT_NAME
: 用户昵称CHANNEL
: 用户初始化渠道(例如 xiaomi、huawei 等)ENABLE_SYNC_ATTRIBUTION
: 是否开启同步获取归因信息,具体请参考同步归因
注意
- 首次调用后,需要等
InitializeCallback
回调的onSuccess
回调成功之后才能继续调用其他事件上报的方法 - 初始化方法调用成功之后,后续冷启动可以不再调用,只需要正常启动 SDK 即可(多次调用也不会有问题,引力做了兼容)
4. 行为事件上报
4.1 业务注册事件上报(可选)
当用户完成应用内业务注册后,您可以调用 trackRegisterEvent
方法来上报用户注册事件($AppRegister
)给引力,引力会使用该事件统计指标:标准_注册数。
gravityEngineSDKInstance.trackRegisterEvent();
相关信息
该方法可多次调用,每次调用都会上报一个用户注册事件(计算指标时会去重)。
4.2 付费事件上报
当用户发生付费行为时,需要调用 trackPayEvent
方法记录用户付费事件,此事件非常重要,会影响买量和 ROI 统计,请务必重点测试!
/**
* 上报付费事件
* @param payAmount 付费金额 单位为分
* @param payType 货币类型 按照国际标准组织ISO 4217中规范的3位字母,例如CNY人民币、USD美金等
* @param orderId 订单号
* @param payReason 付费原因 例如:购买钻石、办理月卡
* @param payMethod 付费方式 例如:支付宝、微信、银联等
*/
gravityEngineSDKInstance.trackPayEvent(300, "CNY", "order_id" + System.currentTimeMillis(), "月卡", "支付宝");
相关信息
如果您需要通过后端 API 方式上报付费事件,请参考 混合上报模式 来接入事件上报接口报送付费事件。
警告
- 参数
payAmount
单位为分,请务必注意,传错单位可能会导致买量受到影响! - 引力引擎会通过订单号
orderId
去重,避免重复上报,请务必传入!
4.3 广告观看事件上报
若您的产品内有广告变现,则需要在用户点击广告观看的同时上报用户广告观看事件给引力,具体参考如下:
/**
* 上报广告观看事件 参数如下
* @param adUnionType 广告聚合平台类型 (取值为:topon、gromore、admore、self,分别对应Topon、Gromore、Admore、自建聚合)
* @param adPlacementId 广告瀑布流ID(广告位ID)
* @param adSourceId 广告源ID(代码位ID)
* @param adType 广告类型 (取值为:reward、banner、 native 、interstitial、 splash ,分别对应激励视频广告、横幅广告、信息流广告、插屏广告、开屏广告)
* @param adnType 广告平台类型(取值为:csj、gdt、ks、 mint 、baidu、other,分别对应为穿山甲、优量汇、快手联盟、Mintegral、百度联盟、其他平台)
* @param ecpm 预估ECPM价格(单位为元)
*/
// 上报广告观看事件
gravityEngineSDKInstance.trackAdShowEvent("topon", "placement_id", "ad_source_id", "reward", "csj", 1);
警告
参数 ecpm
单位为元,请务必注意,做好单位转换,传错单位可能会导致买量受到影响!
4.4 提现事件上报(可选)
当用户发生应用内提现行为时,需要调用 trackWithdrawEvent
方法记录用户提现事件!
/**
* 上报提现事件
* @param payAmount 提现金额 单位为分
* @param payType 货币类型 按照国际标准组织ISO 4217中规范的3位字母,例如CNY人民币、USD美金等
* @param orderId 订单号
* @param payReason 提现原因 例如:用户首次提现、用户抽奖提现
* @param payMethod 提现支付方式 例如:支付宝、微信、银联等
* @param isFirstPay 是否首次提现
*/
gravityEngineSDKInstance.trackWithdrawEvent(300, "CNY", "order_id" + System.currentTimeMillis(), "用户首次提现", "支付宝", true);
4.5 设置公共事件属性
对于一些重要的属性,譬如玩家的区服和渠道等,这些属性需要设置在每个事件中,此时您可以将这些属性设置为公共事件属性。公共事件属性指的就是每个事件都会带有的属性,您可以调用 setSuperProperties
来设置公共事件属性,我们推荐您在发送事件前,先设置公共事件属性。
JSONObject superProperties = new JSONObject();
superProperties.put("AGE",29);
superProperties.put("CHANNEL","xiaomi");
gravityEngineSDKInstance.setSuperProperties(superProperties);
公共事件属性将会被保存到缓存中,无需每次启动 APP 时调用。如果调用 setSuperProperties
上传了先前已设置过的公共事件属性,则会覆盖之前的属性。如果公共事件属性和 track()
上传的某个属性的 Key 重复,则该事件的属性会覆盖公共事件属性。
- 如果您需要删除某个公共事件属性,可以调用
unsetSuperProperty
清除其中一个公共事件属性; - 如果您想要清空所有公共事件属性,则可以调用
clearSuperProperties
; - 如果您想要获取所有公共事件属性,可以调用
getSuperProperties
;
// 清除属性名为 CHANNEL 的公共属性
gravityEngineSDKInstance.unsetSuperProperty("CHANNEL");
// 清空所有公共属性
gravityEngineSDKInstance.clearSuperProperties();
// 获取所有公共属性
gravityEngineSDKInstance.getSuperProperties();
注意
公共属性需要先在事件属性中添加,否则会上报失败!
4.6 记录事件时长
如果您需要记录某个事件持续时长,您可以调用 timeEvent
来开始计时,配置您想要计时的事件名称,当您上传该事件时,将会自动在您的事件属性中加入 $event_duration
这一属性来表示记录的时长,单位为秒。
// 调用 timeEvent 开启对 TIME_EVENT 事件的计时
gravityEngineSDKInstance.timeEvent("TIME_EVENT");
// do some thing...
// 通过 track 上传 TIME_EVENT 事件时,会在属性中添加 $event_duration 属性
gravityEngineSDKInstance.track("TIME_EVENT");
4.7 立即上报事件
如果需要立即上报缓存的事件,可以调用 flush
来上报所有缓存的事件。
// 调用 flush() 上报缓存事件
gravityEngineSDKInstance.flush();
4.8 上报自定义事件
您可以调用 track
方法,记录用户自定义事件。
建议您先在元事件中添加自定义事件,然后在游戏中指定位置埋点调用 track
方法上报自定义事件。
JSONObject jsonObject = new JSONObject();
jsonObject.put("guild_id", "100");
jsonObject.put("guild_level", 10);
jsonObject.put("guild_name", "北方之狼");
gravityEngineSDKInstance.track("AddGuild", jsonObject);
- 事件名称是
String
类型,只能以字母开头,可包含数字,字母和下划线 “_”,长度最大为 50 个字符。 - 事件属性是
Map<String, Object>
类型,其中每个元素代表一个属性;- 事件属性
Key
为属性名称,为String
类型,规定只能以字母开头,包含数字,字母和下划线 “_”,长度最大为 50 个字符; - 属性
Value
支持String
、int
、float
、boolean
、Date
、List<String>
;
- 事件属性
当您调用 track
时,SDK 会取系统当前时间作为事件发生的时刻,如果您需要指定事件时间,可以传入 Date
类型的参数来设置事件触发时间。
SDK 提供了时间校准接口,允许使用服务器时间对 SDK 时间进行校准,具体请参考 Demo 中对 calibrateTime
和 calibrateTimeWithNtp
方法的使用。
注意
尽管事件可以设置触发时间,但是接收端会做如下的限制:只接收相对服务器时间在前 10 天至后 1 小时的数据,超过时限的数据将会被视为异常数据,整条数据无法入库!
5. 用户属性上报
目前支持的用户属性设置接口为 user_set
、user_setOnce
、user_increment
、user_max
、user_min
、user_append
、user_uniqAppend
、user_unset
、user_delete
。
5.1 设置用户属性
对于一般的用户属性,您可以调用 user_set
来进行设置,使用该接口上传的属性将会覆盖原有的属性值,如果之前不存在该用户属性,则会新建该用户属性。
// 若某key已存在则覆盖,否则将自动创建并赋值
JSONObject jsonObject = new JSONObject();
jsonObject.put("$name", "turboUserName");
jsonObject.put("$gender", "男");
gravityEngineSDKInstance.user_set(jsonObject);
5.2 初始化用户属性
对于只在首次设置时有效的属性,我们可以使用 user_setOnce
记录这些属性。与 user_set
方法不同的是,如果被设置的用户属性已存在,则这条记录会被忽略而不会覆盖已有数据,如果属性不存在则会自动创建。因此,user_setOnce
适用于为用户设置首次激活时间、首次注册时间等属性。例如:
JSONObject jsonObject = new JSONObject();
jsonObject.put("$gender", "male");
gravityEngineSDKInstance.user_setOnce(jsonObject);
5.3 累加用户属性
对于数值型的用户属性,可以使用 user_increment
对属性值进行累加。常用于记录用户付费次数、付费额度、积分等属性。例如:
// 增加或减少一个用户的某个NUMBER类型的Profile值
gravityEngineSDKInstance.user_increment("$age", 27);
5.4 用户属性取最大值
对于数值型的用户属性,可以使用 user_max
用来比较数值大小,保存较大的,如果没有这个 key,则新增 key,value 取本次的值
gravityEngineSDKInstance.user_max("ad_ecpm_max", 300);
5.5 用户属性取最小值
对于数值型的用户属性,可以使用 user_min
用来比较数值大小,保存较小的,如果没有这个 key,则新增 key,value 取本次的值
gravityEngineSDKInstance.user_min("ad_ecpm_min", 100);
5.6 Array 追加
对用户喜爱的电影、用户点评过的餐厅等属性,可以调用 user_append
记录列表型属性,例如:
// 向某个用户的某个数组类型的用户表添加一个或者多个值,默认不去重
JSONArray moviesJsonArray = new JSONArray();
moviesJsonArray.put("Interstellar");
moviesJsonArray.put("The Negro Motorist Green Book");
JSONObject jsonObject = new JSONObject();
jsonObject.put("Movies", moviesJsonArray);
gravityEngineSDKInstance.user_append(jsonObject);
5.7 Array 去重追加
调用 user_uniqAppend
用来对 Array 类型的用户数据去重追加元素,例如:
// 向某个用户的某个数组类型的用户表添加一个或者多个值,会做去重
JSONArray moviesJsonArray = new JSONArray();
moviesJsonArray.put("Interstellar");
moviesJsonArray.put("The Negro Motorist Green Book");
JSONObject jsonObject = new JSONObject();
jsonObject.put("Movies", moviesJsonArray);
gravityEngineSDKInstance.user_uniqAppend(jsonObject);
5.8 清空用户属性
调用 user_delete
方法,将把当前用户属性清空,您将无法再查询该名用户的用户属性,但该用户产生的事件仍然可以被查询到
// // 删除一个用户的所有属性值
gravityEngineSDKInstance.user_delete();
5.9 重置用户属性
如果需要重置已设置的某个用户属性,可以调用 user_unset
进行取消:
// 将某个用户的某些属性值设置为空
gravityEngineSDKInstance.user_unset("$name");
6. 其他功能
6.1 集成 OAID
匿名设备标识符(Open Anonymous Device Identifier,简称 OAID)是一种用于安卓设备的唯一标识符,可由用户重置。该标识符由移动安全联盟(MSA)、中国信息通信研究院以及设备厂商合力推出,旨在替代 IMEI 等不可重置的设备标识符,以保护用户隐私。
使用最新的 MSA SDK 版本,才能支持市面上最新推出的手机,进而提升 OAID 的获取率,由于归因匹配很大程度上依赖 OAID 完成,所以使用最新版本的 MSA SDK 对于降低您应用的买量成本至关重要!
引力引擎 SDK 支持最新版本的 MSA SDK!需要您按照如下步骤进行手动集成。
6.1.1 集成 OAID
- 在MSA 官网注册账号;
- 按照要求发送申请文件到 MSA 官方邮箱账号,申请证书;
- 证书申请完成之后,将
supplierconfig.json
、应用包名.cert.pem
、aar
文件放在项目中合适的位置; - 按照 MSA 文档添加混淆配置。
引力引擎会默认读取 assets
中命名为应用包名.cert.pem
的文件当做签名文件初始化 MSA SDK。
注意
应用包名.cert.pem
中应用包名要替换成你自己的应用包名!
如果你需要自定义签名文件的路径,可以使用如下方法进行设置
/**
* 定义 oaid 证书在 assets 中的文件相对路径
*
* @param filePath oaid 证书在 assets 中的相对路径,eg:"file/test.cert.pom"
*/
OaidHelper.setOaidCertFilePath(filePath)
6.1.2 获取 OAID
如您有获取 OAID 字符串的需要,可以按照如下方式获取
OaidHelper.getOpenAdIdentifier(mContext);
警告
请注意该接口是同步接口,必须子线程中使用!经过测试,耗时在 10 - 1000ms 之间。
6.2 自动采集事件
引力引擎 SDK 支持自动采集一些基础事件以降低您的接入成本,您可以参考自动采集一文来快速开启。
6.3 开启 Debug 模式
SDK 支持在两种模式下运行:
Normal
: 线上模式,数据会存入缓存,并依据一定的缓存策略上报Debug
: 测试模式,数据逐条上报。当出现问题时会以日志和异常的方式提示用户,您也可以去事件流中查看实时上报的数据数,辅助您判断数据接入是否正常。
您可以通过如下方式来开启 Debug
GEConfig config = GEConfig.getInstance(mContext, Constants.ACCESS_TOKEN);
config.setMode(GEConfig.ModeEnum.DEBUG);
警告
Debug 模式仅仅用于集成阶段数据校验,不要在生产模式下使用!
6.4 绑定三方平台
引力支持与其他三方的数据分析平台打通,具体调用如下:
6.4.1 数数
gravityEngineSDKInstance.bindTAThirdPlatform(CURRENT_USER_TA_ACCOUNT_ID, CURRENT_USER_TA_DISTINCT_ID);
参数说明:
CURRENT_USER_TA_ACCOUNT_ID
:当前用户的数数账户 ID (#account_id)CURRENT_USER_TA_DISTINCT_ID
:当前用户的数数访客 ID (#distinct_id)
提示
引力会自动将引力 client ID
和您传入的数数 account_id
以及 distinct_id
做关联,在回调数数接口时,通过这个关联传递对应的 account_id
、distinct_id
给数数后台
7. 发版记录
版本 | 日期 | 备注 |
---|---|---|
4.1.3 | 2023-03-14 | 重构上线,解除 okhttp 和 androidx 依赖,优化事件采集性能。 |
4.1.5 | 2023-03-16 | 支持全埋点自采集方案 |
4.1.6 | 2023-03-20 | 支持自动标记是否首次付费属性 |
4.1.8 | 2023-04-03 | 1. 自动采集注册事件;2. 广告观看事件立即上报,避免数据 gap |
4.2.0 | 2023-04-17 | 优化 login 方法 |
4.2.1 | 2023-04-19 | 性能优化 |
4.2.2 | 2023-05-20 | 自动采集是否首次付费字段 |
4.2.3 | 2023-05-25 | 修复线上可能的崩溃,优化性能 |
4.2.4 | 2023-06-12 | 优化唯一 ID 逻辑,开放获取 |
4.2.5 | 2023-06-14 | 性能优化 |
4.2.6 | 2023-06-16 | 支持 Unity 原生 Android 项目打通 |
4.2.7 | 2023-06-23 | 性能优化 |
4.2.8 | 2023-06-29 | 性能优化 |
4.3.1 | 2023-07-13 | 支持重置 Client ID;支持打通三方数据平台 |
4.3.2 | 2023-07-14 | 性能优化 |
4.5.3 | 2023-08-30 | 支持查询用户信息接口 |
4.5.5 | 2023-09-20 | 支持同步获取归因结果信息 |
4.5.7 | 2023-10-20 | 注册接口支持返回注册的结构体信息;修复混淆问题 |
4.6.2 | 2023-11-06 | 优化 ID 获取逻辑 |
4.6.3 | 2023-11-23 | 优化 ID 获取逻辑 |
4.7.2 | 2023-12-11 | 接入流程优化,不再自动采集$AppRegister 事件 |
4.7.3 | 2023-12-26 | 支持历史用户初始化 |
4.7.4 | 2023-12-26 | 放开可见性问题 |
4.7.5 | 2024-01-22 | 优化性能问题 |
4.7.8 | 2024-03-03 | 优化设备信息绑定逻辑 |
4.8.3 | 2024-04-15 | bug fix |
4.8.4 | 2024-04-22 | 支持立即上报设备信息,优化设备信息采集成功率 |
4.8.6 | 2024-05-05 | 支持传入 mas 秘钥字符串;支持获取预置属性信息 |
4.8.9 | 2024-08-01 | 适配高版本 |
4.8.10 | 2024-08-28 | 优化性能 |
4.8.11 | 2024-09-26 | 优化性能 |
4.8.12 | 2024-11-12 | Unity 支持演练模式 |