Android SDK Weex 框架支持

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

最新版本为：2.0.0

更新时间为：2020-06-06

1. 集成 SDK

a) 集成Android SDK与Weex支持文件

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

完成Android SDK的集成后，请点此下载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 使用指南

b) 在JS文件中获取模块

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

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

c) 在Weex中使用SDK功能

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

2. 设置用户 ID

a) 设置访客 ID （可选）

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

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

b) 设置账号 ID

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

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

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

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

c) 清除账号 ID

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

    tamodal.logout({'appID': 'YOUR_APPID'})

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

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

3. 发送事件

a) 发送事件

您可以调用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 时间接口来统一使用服务端时间完成数据采集，请参考校准时间小节。

b) 设置公共事件属性

对于一些重要的属性，譬如用户的会员等级、来源渠道等，这些属性需要设置在每个事件中，此时您可以将这些属性设置为公共事件属性。公共事件属性指的就是每个事件都会带有的属性，您可以调用 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'})

c) 记录事件时长

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

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

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

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

4.用户属性

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

a) userSet

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

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

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

b) userSetOnce

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

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

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

c) userAdd

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

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

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

d) userUnset

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

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

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

e) userDel

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

    tamodal.userDel({'appID': 'YOUR_APPID'})

f) userAppend

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

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

5. 自动采集事件(手动集成暂不支持此功能)

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

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

RN 中的调用方法如下：

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

6. SDK配置

a) 暂停/停止数据上报

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

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
      })

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'})

b) 校准时间

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 接口, 可以打开或关闭实例上报功能
  • 支持事件和用户属性数据上报
  • 支持公共事件属性

results matching ""

    No results matching ""