# Android SDK Weex 框架支持

本指南将会为您介绍如何在 Weex 中使用 Android SDK 的功能。

最新版本为:2.0.0

更新时间为:2020-06-06

# 一、集成 SDK

# 1.1 集成 Android SDK 与 Weex 支持文件

集成 Android SDK 请参见Android SDK 使用指南

完成 Android SDK 的集成后,请点此下载 (opens new window)Weex 支持文件,解压后将WeexThinkingDataAnalyticsModule.java文件添加到您的项目工程中

文件添加完成后,在 Application 的 onCreate 方法中添加 WeexThinkingDataAnalyticsModule 模块

 try {
      WXSDKEngine.registerModule("WeexThinkingDataAnalyticsModule", WeexThinkingDataAnalyticsModule.class);
    } catch (WXException e) {
      e.printStackTrace();
    }

另外,Android SDK 可以通过 AndroidManifest.xml 修改部分全局设置,一般情况下,使用默认设置即可。可以打开 Log 功能。

设置上传的网络条件,在默认情况下,SDK 将会网络条件为在 3G, 4G 及 Wifi 时上传数据,您可以通过 setNetworkType 方法修改允许上传的网络条件。

Android SDK 自 v2.3.0 版本开始,SDK 可以设置自签证书。

Android SDK 自 v2.3.0 版本开始,客户端 SDK 支持 Debug 模式。

Android SDK 自 v2.3.1 版本开始支持设置默认时区,可以根据需要配置。

请参见Android SDK 使用指南

# 1.2 在 JS 文件中获取模块

请在具体使用的 JS 文件中加入以下代码:

var tamodal = weex.requireModule("WeexThinkingDataAnalyticsModule");

# 1.3 在 Weex 中使用 SDK 功能

完成导入后即可在 RN 中使用 SDK 功能

# 二、设置用户 ID

# 2.1 设置访客 ID (可选)

如果您的 App 对每个用户有自己的访客 ID 管理体系,则您可以调用 identify 来设置访客 ID:

tamodal.identify({
  appID: "YOUR_APPID",
  distinctId: "distinctId1"
});

# 2.2 设置账号 ID

在用户进行登录时,可调用 login 来设置用户的账号 ID,在设置完账号 ID 后,将会以账号 ID 作为身份识别 ID,并且设置的账号 ID 将会在调用 logout 之前一直保留:

tamodal.login({
  appID: "YOUR_APPID",
  loginId: "weex_textlogin"
});

login 可以多次调用,每次调用会判断传入的账号 ID 与先前保存的 ID 是否一致,一致则忽略调用,不一致则会覆盖先前的 ID。

请注意,该方法不会上传用户登录的事件

# 2.3 清除账号 ID

在用户产生登出行为之后,可调用 logout 来清除账号 ID,在下次调用 login 之前,将会以访客 ID 作为身份识别 ID:

tamodal.logout({ appID: "YOUR_APPID" });

我们推荐您在显性的登出事件时调用 logout,比如用户产生了注销账号这一行为时才调用,而不需要在关闭 App 时调用。

请注意,该方法不会上传用户登出的事件

# 三、发送事件

# 3.1 发送事件

您可以调用track来上传事件,本接口将会调用 SDK 中的track接口,详细的使用说明请参考 SDK 文档中的track接口的介绍:

tamodal.track({
  appID: "YOUR_APPID",
  eventName: "track"
});

tamodal.track({
  appID: "YOUR_APPID",
  eventName: "rn_texttrack",
  properties: {
    KEY_NUMBER: 1.02,
    KEY_STRING: "name",
    KEY_LIST: [1, 2, 3],
    KEY_BOOL: true,
    KEY_DateTime: "2020-05-12 06:27:18.371"
  },
  time: new Date("May 17, 2020 03:24:00").getTime(),
  timeZone: "UTC"
});

eventName 为该事件的事件名,properties 为该事件的所有属性,在 Android SDK v2.2.0 版本中加入了设置事件触发时间及时间偏移的方法重载,支持传入 time 类型的参数来设置事件触发时间,以 timeZone 来设置时间偏移。不传入该参数,则取 track 被调用时的本机时间以及偏移作为事件触发时间以及时区偏移。

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

自 Android SDK v2.3.1 版本开始,您可以通过设置 SDK 默认时区的方式,对齐多个时区下的事件时间,请参考Android SDK 使用指南设置默认时区小节。自 Android SDK v2.5.0 开始,您可以通过校准 SDK 时间接口来统一使用服务端时间完成数据采集,请参考校准时间小节

# 3.2 设置公共事件属性

对于一些重要的属性,譬如用户的会员等级、来源渠道等,这些属性需要设置在每个事件中,此时您可以将这些属性设置为公共事件属性。公共事件属性指的就是每个事件都会带有的属性,您可以调用 setSuperProperties 来设置公共事件属性,我们推荐您在发送事件前,先设置公共事件属性。

公共事件属性的格式要求与事件属性一致。

tamodal.setSuperProperties({
  appID: "YOUR_APPID",
  properties: { superKey: 1, superKey2: "value" }
});

如果您需要删除某个公共事件属性,您可以调用 unsetSuperProperty 清除指定的公共事件属性;如果您想要清空所有公共事件属性,则可以调用 clearSuperProperties

tamodal.unsetSuperProperty({
  appID: "YOUR_APPID",
  properties: "superKey"
});

tamodal.clearSuperProperties({ appID: "YOUR_APPID" });

# 3.3 记录事件时长

您可以调用 timeEvent 来开始计时,配置您想要计时的事件名称,当您上传该事件时,将会自动在您的事件属性中加入 #duration这一属性来表示记录的时长,单位为秒。

tamodal.timeEvent({
  appID: "YOUR_APPID",
  eventName: "rn_texttrack"
});

传入的参数即为需要记录时间的事件的事件名,当该事件被触发时,计时将会停止,并且 #duration 这一计时属性将会被记录在事件中

在 RN 中设置的计时可记录 Android SDK 上传的对应事件,同样 Android SDK 设置的计时可记录 RN 中上传的对应事件

# 四、用户属性

TA 平台目前支持的用户属性设置接口为 userSet、userSetOnce、userAdd、userUnset、userDel 与 userAppend

# 4.1 userSet

对于一般的用户属性,您可以调用 userSet 来进行设置,使用该接口上传的属性将会覆盖原有的属性值,如果之前不存在该用户属性,则会新建该用户属性,类型与传入属性的类型一致,此处以设置用户名为例:

tamodal.userSet({
  appID: "YOUR_APPID",
  properties: { usersetkey: 2, usersetkey2: "usersetvalue" }
});

userSet 设置的用户属性格式要求与事件属性保持一致。

# 4.2 userSetOnce

如果您要上传的用户属性只要设置一次,则可以调用 userSetOnce 来进行设置,当该属性之前已经有值的时候,将会忽略这条信息,以设置首次付费时间来为例:

tamodal.userSetOnce({
  appID: "YOUR_APPID",
  properties: { name: "yea" }
});

userSetOnce 设置的用户属性格式要求与事件属性保持一致。

# 4.3 userAdd

当您要上传数值型的属性时,您可以调用 userAdd 来对该属性进行累加操作,如果该属性还未被设置,则会赋值 0 后再进行计算,可传入负值,等同于相减操作。此处以累计付费金额为例:

tamodal.userAdd({
  appID: "YOUR_APPID",
  properties: { age: 1 }
});

userAdd 设置的属性类型以及 Key 值的限制与 userSet 一致,但 Value 只允许 Number 类型。

# 4.4 userUnset

当您要清空用户的用户属性值时,您可以调用 userUnset 来对指定属性进行清空操作,如果该属性还未在集群中被创建,则 userUnset 不会创建该属性

tamodal.userUnset({
  appID: "YOUR_APPID",
  properties: "usersetkey"
});

userUnset 传入的参数是用户属性的属性名,类型是字符串或字符串数组,支持可变长参数的形式。

# 4.5 userDel

如果您要删除某个用户,可以调用 userDel 将这名用户删除,您将无法再查询该名用户的用户属性,但该用户产生的事件仍然可以被查询到。

tamodal.userDel({ appID: "YOUR_APPID" });

# 4.6 userAppend

从 Android SDK v2.4.0 开始,您可以调用 userAppend 对 Array 类型的用户属性进行追加操作。

tamodal.userAppend({
  appID: "YOUR_APPID",
  properties: { keyArr: ["age", "2"] }
});

# 五、自动采集事件

请注意,如需使用自动采集功能,请集成自动采集功能的相关依赖项,点此查看添加依赖代码

关于自动采集事件的具体使用方法,请参考 Android SDK 自动采集指南一章。

RN 中的调用方法如下:

tamodal.enableAutoTrack({
  appID: "YOUR_APPID",
  autoTrackType: {
    appStart: true,
    appEnd: true,
    appCrash: true,
    appInstall: true
  }
});

# 六、SDK 配置

# 6.1 暂停/停止数据上报

在 Android SDK v2.1.0 版本中,新增了停止 SDK 实例上报数据的功能,一共有两类停止 SDK 实例上报的接口:

# 6.1.1 暂停 SDK 上报(enableTracking)

您可能希望在一些场景下,暂时停止数据采集以及上报,比如用户处于测试环境中、或者用户登录了一个测试账号,此时您可以调用下列接口,暂时停止 SDK 实例的上报。

您可以通过某一实例(包括主要实例以及轻实例)调用 enableTracking,传入 false 来暂停 SDK 实例的上报,该实例已经设置的 #distinct_id、#account_id、公共属性等将保留;该实例已经采集但还未上报成功的数据将继续尝试上报;后续该实例不能采集以及上报任何新数据、不能设置访客 ID、账户 ID 以及公共属性等,但是可以读取该实例已经设置的公共属性和设备 ID、访客 ID、账号 ID 等信息。

实例的停止状态将会被保存在本地缓存,直到调用 enableTracking,传入 true,SDK 实例将会重新恢复数据采集以及上报,需要注意轻实例因为不进行缓存,因此每次打开 App 后,轻实例的暂停状态不会被保留,将重新开启上报。

// 暂停上报
tamodal.enableTracking({
  appID: "YOUR_APPID",
  enableTracking: false
});

// 恢复上报
tamodal.enableTracking({
  appID: "YOUR_APPID",
  enableTracking: true
});

# 6.1.2 停止 SDK 上报(optOutTracking)

在一些特殊场景下,您可能需要完全停止 SDK 实例的功能,比如在适用 GDPR 的地区,用户选择不提供数据采集权限,则您可以调用如下接口完全关闭 SDK 实例的功能。

optOutTracking 只能通过主要实例调用,与 enableTracking 的最大区别在于,其将会清空该实例的本地缓存,包括本实例的访客 ID,账号 ID,公共属性,以及未上报的数据队列。之后再关闭该实例的采集和上报功能。

tamodal.optOutTracking({ appID: "YOUR_APPID" });

如果您希望关闭 SDK 功能的同时,删除该用户在 TA 集群中的用户数据,可以调用 optOutTrackingAndDeleteUser,这将会在停止 SDK 实例的功能前,上报一条 userDel 数据,以删除该用户的用户数据。

tamodal.optOutTrackingAndDeleteUser({ appID: "YOUR_APPID" });

实例的停止状态也将保存在本地缓存,直到调用 optInTracking,后续可以继续上报,但此时相当于一个全新的实例

tamodal.optInTracking({ appID: "YOUR_APPID" });

# 6.2 校准时间

SDK 默认会使用本机时间作为事件发生时间上报,如果用户手动修改设备时间会影响到您的业务分析,自 Android SDK v2.5.0 版本开始,您可以使用从服务端获取的当前时间戳对 SDK 的时间进行校准。此后,所有未指定时间的调用,包括事件数据和用户属性设置操作,都会使用校准后的时间作为发生时间。

// 1585633785954 为当前 unix 时间戳,单位为毫秒,对应北京时间 2020-03-31 13:49:45
tamodal.calibrateTime({ timeStampMillis: 1585633785954 });

我们也提供了从 NTP 获取时间对 SDK 校准的功能。您需要传入您的用户可以访问的 NTP 服务器地址。之后 SDK 会尝试从传入的 NTP 服务地址中获取当前时间,并对 SDK 时间进行校准。如果在默认的超时时间(3 秒)之内,未获取正确的返回结果,后续将使用本地时间上报数据。

// 使用苹果公司 NTP 服务对时间进行校准
tamodal.calibrateTimeWithNtp({ ntpServer: "time.apple.com" });

注意:

  • 您需要谨慎地选择您的 NTP 服务器地址,以保证网络状况良好的情况下,用户设备可以很快的获取到服务器时间。
  • 使用 NTP 服务进行时间校准存在一定的不确定性,建议您优先考虑用时间戳校准的方式。

除了以上校准时间接口外,在 Android SDK v2.5.0 提供了所有用户属性接口的时间函数重载,您可以在调用用户属性相关接口时,传入 Date 对象,则系统会使用传入的 Date 对象来设定数据的 #time 字段。

# ChangeLog

# v2.0.0 2020/06/06

  • 新增 API 接口
  • 支持多实例
  • 支持自动采集事件(新增 APP 安装事件,启动事件,关闭事件,崩溃事件)
  • 支持客户端 SDK 的时间校准功能
  • 新增 optOutTracking/optInTracking 接口
  • 新增 enableTracking 接口, 可以打开或关闭实例上报功能
  • 支持事件和用户属性数据上报
  • 支持公共事件属性