Android SDK RN 框架支持

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

最新版本为：2.1.0

更新时间为：2020-08-27

1. 集成 SDK

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

完成 Android SDK 的集成后，请点此下载 RN 支持文件，解压后将RNThinkingAnalyticsModule.java文件添加到您的项目工程中

文件添加完成后，在项目 Package 的 createNativeModules 方法中添加 RNThinkingAnalyticsModule 模块

modules.add(new RNThinkingAnalyticsModule(reactContext));

另外，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 文件中加入以下代码，以导入模块：

import { NativeModules } from 'react-native';
const RNThinkingAnalyticsModule=NativeModules.RNThinkingAnalyticsModule;

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

2. 设置用户 ID

a) 设置访客 ID （可选）

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

    RNThinkingAnalyticsModule.identify({"appid": "YOUR_APPID",
                                         "distinctId":"distinctId1"})

b) 设置账号 ID

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

    RNThinkingAnalyticsModule.login({"appid": "YOUR_APPID",
                                     "loginId":"account_id"})

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

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

c) 清除账号 ID

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

    RNThinkingAnalyticsModule.logout({"appid": "YOUR_APPID"})

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

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

3. 发送事件

a) 发送事件

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

   RNThinkingAnalyticsModule.track({"appid": "YOUR_APPID", 
                                    "eventName": "rn_texttrack"})

   RNThinkingAnalyticsModule.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().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 来设置公共事件属性，我们推荐您在发送事件前，先设置公共事件属性。

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

    RNThinkingAnalyticsModule.setSuperProperties({"appid": "YOUR_APPID",
                                                   "properties":{"superKey":1, "superKey2":"value"}})

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

    RNThinkingAnalyticsModule.unsetSuperProperty({"appid": "YOUR_APPID",
                                                  "properties":"superKey"})

    RNThinkingAnalyticsModule.clearSuperProperties({"appid": "YOUR_APPID"})

c) 记录事件时长

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

    RNThinkingAnalyticsModule.timeEvent({"appid": "YOUR_APPID",
                                         "eventName": "track"})

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

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

4.用户属性

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

a) userSet

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

    RNThinkingAnalyticsModule.userSet({"appid": "YOUR_APPID",
                                       "properties":{"usersetkey":2,"usersetkey2":"usersetvalue"}})

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

b) userSetOnce

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

    RNThinkingAnalyticsModule.userSetOnce({"appid": "YOUR_APPID",
                                           "properties":{"name":"yea"}})

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

c) userAdd

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

    RNThinkingAnalyticsModule.userAdd({"appid": "YOUR_APPID",
                                       "properties":{"age":1}})

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

d) userUnset

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

     RNThinkingAnalyticsModule.userUnset({"appid": "YOUR_APPID",
                                         "properties":"usersetkey"})

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

e) userDel

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

    RNThinkingAnalyticsModule.userDel({"appid": "YOUR_APPID"})

f) userAppend

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

    RNThinkingAnalyticsModule.userAppend({"appid": "YOUR_APPID",
                                          "properties":{"key":["age","2"]}})

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

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

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

RN 中的调用方法如下：

    RNThinkingAnalyticsModule.enableAutoTrack({"appid": "YOUR_APPID",
                                               "autoTrackType": {"appStart": true, 
                                                                 "appEnd": true, 
                                                                 "appViewCrash": 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 后，轻实例的暂停状态不会被保留，将重新开启上报。

    RNThinkingAnalyticsModule.enableTracking({"appid": "YOUR_APPID",
                                              "enableTracking":true})
    RNThinkingAnalyticsModule.enableTracking({"appid": "YOUR_APPID",
                                              "enableTracking":false})

2. 停止SDK上报（optOutTracking）

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

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

    RNThinkingAnalyticsModule.optOutTracking({"appid": "YOUR_APPID"})

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

    RNThinkingAnalyticsModule.optOutTrackingAndDeleteUser({"appid": "YOUR_APPID"})

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

    RNThinkingAnalyticsModule.optInTracking({"appid": "YOUR_APPID"})

b) 校准时间

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

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

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

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

注意：

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

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

7. 进阶功能

从 v2.1.0 开始，SDK 支持上报三种特殊类型事件: 首次事件、可更新事件、可重写事件。这三种事件需要配合 TA 系统 2.8 及之后的版本使用。由于特殊事件只在某些特定场景下适用，所以请在数数科技的客户成功和分析师的帮助下使用特殊事件上报数据。

7.1 首次事件

首次事件是指针对某个设备或者其他维度的 ID，只会记录一次的事件。例如在一些场景下，您可能希望记录在某个设备上第一次发生的事件，则可以用首次事件来上报数据。

// 示例：上报设备首次事件, 假设事件名为 DEVICE_FIRST
RNThinkingAnalyticsModule.trackFirstEvent({"appid": "YOUR_APPID",
                                           "eventName": "DEVICE_FIRST",
                                           "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"}})

如果您希望以设备以外的其他维度来判断是否首次，则可以为首次事件设置 FIRST_CHECK_ID. 例如您需要记录某个账号的首次事件，可以将账号 ID 设置为首次事件的 FIRST_CHECK_ID:

// 示例：上报用户账号的首次事件, 假设事件名为 USER_FIRST
RNThinkingAnalyticsModule.trackFirstEvent({"appid": "YOUR_APPID",
                                           "eventName": "DEVICE_FIRST",
                                           "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"}, 
                                           "eventId":"YOUR_ACCOUNT_ID"})

注意：由于在服务端完成对是否首次的校验，首次事件默认会延时 1 小时入库。

7.2 可更新事件

您可以通过可更新事件实现特定场景下需要修改事件数据的需求。可更新事件需要指定标识该事件的 ID，并在创建可更新事件对象时传入。TA 后台将根据事件名和事件 ID 来确定需要更新的数据。

// 示例： 上报可被更新的事件，假设事件名为 UPDATABLE_EVENT
RNThinkingAnalyticsModule.trackUpdate({"appid": "YOUR_APPID",
                                       "eventName": "UPDATABLE_EVENT",
                                       "properties": {"status":3, "price":100}, 
                                       "eventId":"test_event_id"})
// 上报后事件属性 status 为 3, price 为 100
RNThinkingAnalyticsModule.trackUpdate({"appid": "YOUR_APPID",
                                       "eventName": "UPDATABLE_EVENT",
                                       "properties": {"status":5}, 
                                       "eventId":"test_event_id"})

可更新事件默认会使用设备当前时间更新历史数据的事件时间，如果您希望指定事件时间，可以在上报可更新事件的时候，指定事件时间:

RNThinkingAnalyticsModule.trackUpdate({"appid": "YOUR_APPID",
                                       "eventName": "OVERWRITE_EVENT",
                                       "eventId":"test_event_id",
                                       "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().getTime(),
                                       "timeZone":"UTC"})

7.3 可重写事件

可重写事件与可更新事件类似，区别在于可重写事件会用最新的数据完全覆盖历史数据，从效果上看相当于删除前一条数据，并入库最新的数据。TA 后台将根据事件名和事件 ID 来确定需要更新的数据。

// 示例： 上报可被重写的事件，假设事件名为 OVERWRITE_EVENT
RNThinkingAnalyticsModule.trackOverwrite({"appid": "YOUR_APPID",
                                          "eventName": "OVERWRITE_EVENT",
                                          "properties": {"status":3, "price":100}, 
                                          "eventId":"test_event_id"})

// 上报后事件属性 status 为 3, price 为 100
RNThinkingAnalyticsModule.trackOverwrite({"appid": "YOUR_APPID",
                                          "eventName": "OVERWRITE_EVENT",
                                          "properties": {"status":5}, 
                                          "eventId":"test_event_id"})
// 上报后事件属性 status 被更新为 5, price 属性被删除

可重写事件默认会使用设备当前时间重写历史数据的事件时间，如果您希望指定事件时间，可以在上报可重写事件的时候，指定事件时间:

RNThinkingAnalyticsModule.trackOverwrite({"appid": "YOUR_APPID",
                                          "eventName": "OVERWRITE_EVENT",
                                          "properties": {"status":5}, 
                                          "eventId":"test_event_id",
                                          "time": new Date().getTime(),
                                          "timeZone":"UTC"})

ChangeLog

v2.1.0 2020/08/27

新增 trackUpdate, trackOverwrite, trackFirstEvent 接口

v2.0.1 2020/06/05

支持 JSONArray 类型

v2.0.0 2020/05/25

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

Android SDK RN 框架支持

Android SDK RN 框架支持

1. 集成 SDK

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

b) 在 JS 文件中导入模块

2. 设置用户 ID

a) 设置访客 ID （可选）

b) 设置账号 ID

c) 清除账号 ID

3. 发送事件

a) 发送事件

b) 设置公共事件属性

c) 记录事件时长

4.用户属性

a) userSet

b) userSetOnce

c) userAdd

d) userUnset

e) userDel

f) userAppend

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

6. SDK配置

a) 暂停/停止数据上报

1. 暂停 SDK 上报（enableTracking）

2. 停止SDK上报（optOutTracking）

b) 校准时间

7. 进阶功能

7.1 首次事件

7.2 可更新事件

7.3 可重写事件

ChangeLog

v2.1.0 2020/08/27

v2.0.1 2020/06/05

v2.0.0 2020/05/25

results matching ""

No results matching ""