# ReactNative SDK 使用指南
本指南将会为您介绍如何在 React Native 中使用 SDK 的功能。
最新版本为:2.2.0
更新时间为:2021-05-26
# 一、集成 SDK
react-native-thinking-data 有自动和手动两种集成方法,推荐使用自动集成
# 1.1 自动集成
# 1. npm 安装 react-native-thinking-data 模块
npm install react-native-thinking-data --save
# 2. link react-native-thinking-data 模块
react-native link react-native-thinking-data(React Native 0.60 以下版本)
cd ios&&pod install(React Native 0.60 以上版本)
# 1.2 手动集成
# 1. npm 安装 react-native-thinking-data 模块
npm install react-native-thinking-data --save
# 2. Android&iOS 平台配置
- iOS
- In XCode, in the project navigator, right click
Libraries
➜Add Files to [your project's name]
- Go to
node_modules
➜react-native-thinking-data
and addRNThinkingData.xcodeproj
- In XCode, in the project navigator, select your project. Add
libRNThinkingData.a
to your project'sBuild Phases
➜Link Binary With Libraries
- Run your project (
Cmd+R
)
- Android
- Open up
android/app/src/main/java/[...]/MainActivity.java
- Add
import cn.thinking.RNThinkingDataPackage;
to the imports at the top of the file - Add
new RNThinkingDataPackage()
to the list returned by thegetPackages()
method
- Append the following lines to
android/settings.gradle
:
include ':react-native-thinking-data'
project(':react-native-thinking-data').projectDir = new File(rootProject.projectDir, '../node_modules/react-native-thinking-data/android')
- Insert the following lines inside the dependencies block in
android/app/build.gradle
:
compile project(':react-native-thinking-data')
完成导入后即可在 ReactNative 中使用 SDK 相关功能
# 1.3 初始化SDK
使用原生方式在Android/iOS原生层完成对应平台SDK的初始化即可
Android SDK初始化参考 其他⽂档 (opens new window)
iOS SDK初始化参考 其他⽂档 (opens new window)
在2.2.0以及之后的版本,可以通过调用init方法来进行SDK的初始化
RNThinkingAnalyticsModule.init({
appid: "xxx",
serverUrl: "https://xxx",
enableEncrypt: true,
secretKey: {
publicKey: "xxx",
version: 1,
symmetricEncryption: "AES",
asymmetricEncryption: "RSA"
},
enableLog: true
});
参数说明:
- appid:是您的项目的 APP ID,可通过在 TA 后台项目管理页面获取
- serverUrl:为数据上传的 URL
- enableLog:是否开启本地log日志
- enableEncrypt:是否开启加密功能,需要配置secretKey
- secretKey:加密相关参数,publicKey加密公钥,version公钥版本号,symmetricEncryption对称加密类型,asymmetricEncryption非对称加密类型,目前只支持AES+RSA加密方式。
# 二、设置用户 ID
# 2.1 设置访客 ID (可选)
如果您的 App 对每个用户有自己的访客 ID 管理体系,则您可以调用 identify
来设置访客 ID:
RNThinkingAnalyticsModule.identify({
appid: "YOUR_APPID",
distinctId: "distinctId1"
});
# 2.2 设置账号 ID
在用户进行登录时,可调用 login
来设置用户的账号 ID,在设置完账号 ID 后,将会以账号 ID 作为身份识别 ID,并且设置的账号 ID 将会在调用 logout
之前一直保留:
RNThinkingAnalyticsModule.login({ appid: "YOUR_APPID", loginId: "account_id" });
login
可以多次调用,每次调用会判断传入的账号 ID 与先前保存的 ID 是否一致,一致则忽略调用,不一致则会覆盖先前的 ID。
请注意,该方法不会上传用户登录的事件
# 2.3 清除账号 ID
在用户产生登出行为之后,可调用 logout
来清除账号 ID,在下次调用 login
之前,将会以访客 ID 作为身份识别 ID:
RNThinkingAnalyticsModule.logout({ appid: "YOUR_APPID" });
我们推荐您在显性的登出事件时调用 logout
,比如用户产生了注销账号这一行为时才调用,而不需要在关闭 App 时调用。
请注意,该方法不会上传用户登出的事件
# 三、发送事件
# 3.1 发送事件
您可以调用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 时间接口来统一使用服务端时间完成数据采集,请参考校准时间小节。
# 3.2 设置公共事件属性
对于一些重要的属性,譬如用户的会员等级、来源渠道等,这些属性需要设置在每个事件中,此时您可以将这些属性设置为公共事件属性。公共事件属性指的就是每个事件都会带有的属性,您可以调用 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" });
如果您想要获取所有公共事件属性,则可以调用 getSuperProperties
async () => {
var properties = await RNThinkingAnalyticsModule.getSuperProperties({
appid: "YOUR_APPID",
})
}
# 3.3 记录事件时长
您可以调用 timeEvent
来开始计时,配置您想要计时的事件名称,当您上传该事件时,将会自动在您的事件属性中加入 #duration
这一属性来表示记录的时长,单位为秒。
RNThinkingAnalyticsModule.timeEvent({
appid: "YOUR_APPID",
eventName: "track"
});
传入的参数即为需要记录时间的事件的事件名,当该事件被触发时,计时将会停止,并且 #duration
这一计时属性将会被记录在事件中
在 RN 中设置的计时可记录 Android SDK 上传的对应事件,同样 Android SDK 设置的计时可记录 RN 中上传的对应事件
# 四、用户属性
TA 平台目前支持的用户属性设置接口为 userSet
、userSetOnce
、userAdd
、userUnset
、userDel
与 userAppend
# 4.1 userSet
对于一般的用户属性,您可以调用 userSet
来进行设置,使用该接口上传的属性将会覆盖原有的属性值,如果之前不存在该用户属性,则会新建该用户属性,类型与传入属性的类型一致,此处以设置用户名为例:
RNThinkingAnalyticsModule.userSet({
appid: "YOUR_APPID",
properties: { usersetkey: 2, usersetkey2: "usersetvalue" }
});
属性格式要求与事件属性保持一致。
# 4.2 userSetOnce
如果您要上传的用户属性只要设置一次,则可以调用 userSetOnce
来进行设置,当该属性之前已经有值的时候,将会忽略这条信息,以设置首次付费时间来为例:
RNThinkingAnalyticsModule.userSetOnce({
appid: "YOUR_APPID",
properties: { name: "yea" }
});
属性格式要求与事件属性保持一致。
# 4.3 userAdd
当您要上传数值型的属性时,您可以调用 userAdd
来对该属性进行累加操作,如果该属性还未被设置,则会赋值 0 后再进行计算,可传入负值,等同于相减操作。此处以累计付费金额为例:
RNThinkingAnalyticsModule.userAdd({
appid: "YOUR_APPID",
properties: { age: 1 }
});
设置的属性key为字符串,Value 只允许为数值。
# 4.4 userUnset
当您要清空用户的用户属性值时,您可以调用 userUnset
来对指定属性进行清空操作,如果该属性还未在集群中被创建,则 userUnset
不会创建该属性
RNThinkingAnalyticsModule.userUnset({
appid: "YOUR_APPID",
properties: "usersetkey"
});
userUnset 传入的参数是用户属性的属性名,类型是字符串或字符串数组,支持可变长参数的形式。
# 4.5 userDel
如果您要删除某个用户,可以调用 userDel
将这名用户删除,您将无法再查询该名用户的用户属性,但该用户产生的事件仍然可以被查询到。
RNThinkingAnalyticsModule.userDel({ appid: "YOUR_APPID" });
# 4.6 userAppend
从 Android SDK v2.4.0 开始,您可以调用 userAppend
对 Array 类型的用户属性进行追加操作。
RNThinkingAnalyticsModule.userAppend({
appid: "YOUR_APPID",
properties: { key: ["age", "2"] }
});
# 4.7 userUniqAppend
从 v2.2.0 版本开始,您可以调用 userUniqAppend
对 数组类型的用户属性进行追加操作。
和 userAppend
接口的区别,调用 userUniqAppend
接口会对追加的用户属性进行去重, userAppend
接口不做去重,用户属性可存在重复。
RNThinkingAnalyticsModule.userUniqAppend({
appid: "YOUR_APPID",
properties: {
'USER_LIST1': ["uuuuu", "3333"],
}
});
# 五、自动采集事件
请注意,如需使用自动采集功能,请集成自动采集功能的相关依赖项,点此查看添加依赖代码
关于自动采集事件的具体使用方法,请参考 Android SDK 自动采集指南一章。
RN 中的调用方法如下:
RNThinkingAnalyticsModule.enableAutoTrack({
appid: "YOUR_APPID",
autoTrackType: {
appStart: true,
appEnd: true,
appViewCrash: true,
appInstall: true
}
});
# 5.1 设置自动采集事件自定义属性
v2.2.0版本,您可以调用 setAutoTrackProperties
设置自定义属性
RNThinkingAnalyticsModule.setAutoTrackProperties({
appid: "YOUR_APPID",
types: ["appStart", "appEnd","appInstall","appViewCrash"],
properties: {
auto_name: "xxx",
auto_age: "xxx"
}
});
# 六、SDK 配置
# 6.1 数据上报状态
在 v2.2.0 版本中,新增了 SDK 数据上报状态,一共有四种状态:
# 6.1.1 暂停 SDK 上报(pause)
您可能希望在一些场景下,暂时停止数据采集以及上报,比如用户处于测试环境中、或者用户登录了一个测试账号,此时您可以调用下列接口,暂时停止 SDK 实例的上报。
您可以通过某一实例(包括主要实例以及轻实例)调用 setTrackStatus
,传入 pause
来暂停 SDK 实例的上报,该实例已经设置的 #distinct_id
、#account_id
、公共属性等将保留;该实例已经采集但还未上报成功的数据将继续尝试上报;后续该实例不能采集以及上报任何新数据、不能设置访客 ID、账户 ID 以及公共属性等,但是可以读取该实例已经设置的公共属性和设备 ID、访客 ID、账号 ID 等信息。
实例的停止状态将会被保存在本地缓存,直到调用 setTrackStatus
,传入 normal
,SDK 实例将会重新恢复数据采集以及上报,需要注意轻实例因为不进行缓存,因此每次打开 App 后,轻实例的暂停状态不会被保留,将重新开启上报。
RNThinkingAnalyticsModule.setTrackStatus({
appid: "YOUR_APPID",
status: "pause"
});
RNThinkingAnalyticsModule.setTrackStatus({
appid: "YOUR_APPID",
status: "normal"
});
# 6.1.2 停止 SDK 上报(stop)
在一些特殊场景下,您可能需要完全停止 SDK 实例的功能,比如在适用 GDPR 的地区,用户选择不提供数据采集权限,则您可以调用如下接口完全关闭 SDK 实例的功能。
将会清空该实例的本地缓存,包括本实例的访客 ID,账号 ID,公共属性,以及未上报的数据队列。之后再关闭该实例的采集和上报功能。
RNThinkingAnalyticsModule.setTrackStatus({
appid: "YOUR_APPID",
status: "stop"
});
实例的停止状态也将保存在本地缓存,直到传入状态 normal
,后续可以继续上报,但此时相当于一个全新的实例
RNThinkingAnalyticsModule.setTrackStatus({
appid: "YOUR_APPID",
status: "normal"
});
# 6.1.3 数据采集入库但暂停上报数据(saveOnly)
您可能希望在一些场景下,暂时停止 SDK 数据的网络上报,以免影响用户体验,比如用户处于游戏战斗场景,此时您可以调用下列接口,暂时停止 SDK 的网络上报。
您可以通过某一实例(包括主要实例以及轻实例)调用 setTrackStatus:
,传入
saveOnly
来暂停 SDK 的网络上报(数据采集依然存在);
实例的停止状态将会被保存在本地缓存,直到调用 setTrackStatus:
传入 normal
,SDK 实例将会把本地库中未上报数据立即上报。
// 可以采集入库 暂停发送数据
RNThinkingAnalyticsModule.setTrackStatus({
appid: "YOUR_APPID",
status: "saveOnly"
});
// 恢复上报
RNThinkingAnalyticsModule.setTrackStatus({
appid: "YOUR_APPID",
status: "normal"
});
# 6.1.4 正常状态(normal)
SDK 正常状态normal
,数据会进行采集并网络上报。
SDK不进行数据上报状态设置的话,就是默认此状态。
RNThinkingAnalyticsModule.setTrackStatus({
appid: "YOUR_APPID",
status: "normal"
});
# 6.2 校准时间
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
字段。
# 6.3 获取访客ID
在 v2.2.0 版本,加入了获取设访客ID(也就是预置属性#distinct_id
)的接口,您可以通过调用 getDistinctId
来获取访客 ID:
async () => {
var distinct_id = await RNThinkingAnalyticsModule.getDistinctId({
appid: "YOUR_APPID",
})
}
# 6.4 获取设备ID
在 v2.2.0 版本,加入了获取设备 ID(也就是预置属性#device_id
)的接口,您可以通过调用 getDeviceId
来获取设备 ID:
async () => {
var device_id = await RNThinkingAnalyticsModule.getDeviceId({
appid: "YOUR_APPID",
})
}
# 6.5 获取预置属性
v2.2.0 及以后的版本可以调用 getPresetProperties()
方法获取预置属性。
async () => {
var presetProperties = await RNThinkingAnalyticsModule.getPresetProperties({
appid: "YOUR_APPID",
})
}
# 七、进阶功能
从 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.2.0 2022/05/26
- 支持三方数据接入
- 支持数据传输加密
- 支持userUniqAppend
- 优化数据停止/暂停上报接口
- 支持预制属性获取
- 自动采集事件支持自定义静态公共属性
- 新增获取静态公共属性接口
- 支持访客ID获取
- 支持设备ID获取
- 优化初始化方式
# v2.1.2 2021/03/16
- 适配iOS 14
- 适配Android 11
- 新增预置属性#bundle_id(应用唯一标识)
- 优化网络信号获取逻辑
# v2.1.1 2020/10/29
- 适配 iOS 5G 网络
- 优化 install,start 事件上报逻辑
- 优化数据传输格式
- 默认网络上报策略调整为 2G/3G/4G/5G/WIFI
# 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 接口, 可以打开或关闭实例上报功能
- 支持事件和用户属性数据上报
- 支持公共事件属性