快速接入

约 4902 字大约 16 分钟

本文档为Android接入 引力引擎open in new window 4.x 版本 的技术接入方案,详细使用请参考 Demo 工程open in new window

提示

在接入前, 请先阅读 接入前准备

注意

在正式上线之前,请参考 接入验证 完成接入校验。

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 手动集成

  1. 下载并解压 最新 Android SDKopen in new window
  2. 在项目 libs 文件夹中添加 GravityEngineSDK.aar
  3. 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);

参数说明:

注意

应用每次启动都要执行 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 即可

3.2 用户登录(可选)

在用户登录成功后调用 login 方法设置用户的 ClientID,SDK 会自动上报登录事件,您无需手动上报。

gravityEngineSDKInstance.login(USER_CLIENT_ID);

参数说明:

  • USER_CLIENT_ID : 用户唯一 ID,同调用 initialize 方法时保持一致

注意

如用户重新登录,则需要重新调用 login 方法,并传入适当的 Client ID 参数,您需要确保传入的Client ID 之前成功调用过 initialize 方法,即当前用户已经完成了初始化流程,如果是完全新的用户,需要走初始化流程调用 initialize 方法!

3.3 用户注销登录(可选)

在用户切换账号、退出登录之后,可以调用 logout 方法清空本地用户缓存的数据,SDK 会自动上报注销登录事件,您无需手动上报。

gravityEngineSDKInstance.logout(new LogoutCallback() {
    @Override
    public void onFinish() {
        Log.d(TAG, "logout call finish");
    }
});

注意

  • 如用户重新登录,则需要重新调用 login 方法,并传入适当的 Client ID 参数,您需要确保传入的Client ID 之前成功调用过 initialize 方法,即当前用户已经完成了初始化流程,如果是完全新的用户,需要先调用 initialize 方法!
  • LogoutCallback回调未完成之前,请不要调用login方法,否则可能会造成数据异常!

3.4 更新引力 Client ID(可选)

在业务完成注册逻辑,并且可以获取稳定的账户 UID (例如:手机号)后,您可以通过调用 resetClientId 方法重置当前用户在引力后台的 client ID,以便使您的业务 UID 和引力 client ID 打通。

gravityEngineSDKInstance.resetClientId(ACCESS_TOKEN, NEW_CLIENT_ID, new ResetCallback() {
    @Override
    public void onFailed(String errorMsg) {
        Log.d(TAG, "reset client id failed " + errorMsg);
    }

    @Override
    public void onSuccess() {
        Log.d(TAG, "reset client id success");
    }
});

参数说明:

  • ACCESS_TOKEN : 项目通行证,同启动 SDK 时保持一致
  • NEW_CLIENT_ID:新的用户 ID,通常是能稳定标识一个用户的 ID,比如手机号、实名认证 ID 等等

警告

请在 resetClientId 方法的 onSuccessonFailed 回调中获取重置结果,如果重置成功,后续引力将使用新的 client ID 来回传数据,如果您有通过 API 方式上报事件给引力的逻辑,请注意上报的 Client ID,也要相应的做出改变,需要使用新的 Client ID。

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(), "月卡", "支付宝");

国际标准组织 ISO 4217 代码表open in new window

相关信息

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

警告

  • 参数 payAmount 单位为分,请务必注意,传错单位可能会导致买量受到影响!
  • 引力引擎会通过订单号 orderId 去重,避免重复上报,请务必传入!

4.3 广告观看事件上报

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

/**
 * 上报广告观看事件 参数如下
 * @param adUnionType   广告聚合平台类型  (取值为:topon、gromore、admore、self,分别对应Topon、Gromore、Admore、自建聚合)
 * @param adPlacementId 广告瀑布流ID
 * @param adSourceId    广告源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);

国际标准组织 ISO 4217 代码表open in new window

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();

注意

公共属性需要先在事件属性open in new window中添加,否则会上报失败!

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 方法,记录用户自定义事件。

建议您先在元事件open in new window中添加自定义事件,然后在游戏中指定位置埋点调用 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 支持StringintfloatbooleanDateList<String>

当您调用 track 时,SDK 会取系统当前时间作为事件发生的时刻,如果您需要指定事件时间,可以传入 Date 类型的参数来设置事件触发时间。

SDK 提供了时间校准接口,允许使用服务器时间对 SDK 时间进行校准,具体请参考 Demo 中对 calibrateTimecalibrateTimeWithNtp 方法的使用。

注意

尽管事件可以设置触发时间,但是接收端会做如下的限制:只接收相对服务器时间在前 10 天至后 1 小时的数据,超过时限的数据将会被视为异常数据,整条数据无法入库!


5. 用户属性上报

目前支持的用户属性设置接口为 user_setuser_setOnceuser_incrementuser_maxuser_minuser_appenduser_uniqAppenduser_unsetuser_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 官网open in new window注册账号;
  • 按照要求发送申请文件到 MSA 官方邮箱账号,申请证书;
  • 证书申请完成之后,将supplierconfig.json应用包名.cert.pemaar 文件放在项目中合适的位置;
  • 按照 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: 测试模式,数据逐条上报。当出现问题时会以日志和异常的方式提示用户,您也可以去事件流open in new window中查看实时上报的数据数,辅助您判断数据接入是否正常。

您可以通过如下方式来开启 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_iddistinct_id 给数数后台

6.5 查询用户信息

4.5.3 版本之后,客户端 SDK 支持获取用户信息,主要包括

  • 用户基础信息(user_info)
  • 用户属性信息(user_properties)
  • 巨量平台信息(bytedance)
  • 巨量星图平台信息(bytedance_star)
  • ASA 平台信息(asa) 仅 iOS 有值

获取方式如下示例:

gravityEngineSDKInstance.queryUserInfo(Constants.ACCESS_TOKEN, new QueryUserInfoCallback() {
    @Override
    public void onFailed(String errorMsg) {
        Log.d(TAG, "query user failed");
    }

    @Override
    public void onSuccess(JSONObject userInfo) {
        Log.d(TAG, "user info is " + userInfo.toString());
    }
});

7. 发版记录

版本日期备注
4.1.32023-03-14重构上线,解除 okhttpandroidx 依赖,优化事件采集性能。
4.1.52023-03-16支持全埋点自采集方案
4.1.62023-03-20支持自动标记是否首次付费属性
4.1.82023-04-031. 自动采集注册事件;2. 广告观看事件立即上报,避免数据 gap
4.2.02023-04-17优化 login 方法
4.2.12023-04-19性能优化
4.2.22023-05-20自动采集是否首次付费字段
4.2.32023-05-25修复线上可能的崩溃,优化性能
4.2.42023-06-12优化唯一 ID 逻辑,开放获取
4.2.52023-06-14性能优化
4.2.62023-06-16支持 Unity 原生 Android 项目打通
4.2.72023-06-23性能优化
4.2.82023-06-29性能优化
4.3.12023-07-13支持重置 Client ID;支持打通三方数据平台
4.3.22023-07-14性能优化
4.5.32023-08-30支持查询用户信息接口
4.5.52023-09-20支持同步获取归因结果信息
4.5.72023-10-20注册接口支持返回注册的结构体信息;修复混淆问题
4.6.22023-11-06优化 ID 获取逻辑
4.6.32023-11-23优化 ID 获取逻辑
4.7.22023-12-11接入流程优化,不再自动采集$AppRegister 事件
4.7.32023-12-26支持历史用户初始化
4.7.42023-12-26放开可见性问题
4.7.52024-01-22优化性能问题
4.7.82024-03-03优化设备信息绑定逻辑
4.8.32024-04-15bug fix
4.8.42024-04-22支持立即上报设备信息,优化设备信息采集成功率
4.8.62024-05-05支持传入 mas 秘钥字符串;支持获取预置属性信息