iOS SDK RN 框架支持
本指南将会为您介绍如何在 React Native 中使用 iOS SDK 的功能。
最新版本为:2.1.0
更新时间为:2020-08-27
1. 集成 SDK
a) 集成iOS SDK与RN支持文件
集成 iOS SDK 请参见iOS SDK 使用指南
完成 iOS SDK 的集成后,请点此下载 RN 支持文件,解压后将 RNThinkingAnalyticsModule.h
与 RNThinkingAnalyticsModule.m
文件添加到您的项目工程中。
另外,打印数据 Log,可以调用 setLogLevel
方法来开启。
设置上传的网络条件,在默认情况下,SDK 将会网络条件为在 3G, 4G 及 Wifi 时上传数据,您可以通过 setNetworkType
方法修改允许上传的网络条件。
iOS SDK 自 v2.3.0 版本开始,SDK 可以配置 HTTPS 校验方法。
iOS SDK 自 v2.3.1 版本开始支持设置默认时区,可以根据需要配置。
iOS SDK 自 v2.4.0 版本开始,客户端 SDK 支持 Debug 模式。
请参见iOS SDK 使用指南
b) 在 JS 文件中导入模块
请在具体使用的 JS 文件中加入以下代码,以导入模块:
import { NativeModules } from 'react-native';
const RNThinkingAnalyticsModule=NativeModules.RNThinkingAnalyticsModule;
完成导入后即可在 RN 中使用 SDK 功能
在完成导入后,即可使用 SDK 功能,需要注意的是,RN 支持模块只是将 iOS SDK 的接口进行封装,传输数据仍由 iOS SDK 的实例完成的,因此在 iOS SDK 与 RN 传输的数据,将会共用访客 ID、账号 ID 以及事件公共属性。
2. 设置用户 ID
a) 设置访客 ID (可选)
SDK 实例会使用随机 UUID 作为每个用户的默认访客 ID,该 ID 将会作为用户在未登录状态下身份识别 ID。需要注意的是,访客 ID 在用户重新安装 App 以及更换设备时将会变更。
如果用户在您的产品中可以未登录状态下使用,且您需要配置用户在未登录状态下的访客 ID ,则您可以调用 identify
来进行设置:
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"})
在 RN 中的调用 logout 也将清除 iOS SDK 中的账号 ID,同样 iOS SDK 调用 logout 也会清除 RN 中的账号 ID
我们推荐您在显性的登出事件时调用 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
为该事件的所有属性,在 iOS SDK v2.2.0 版本中加入了设置事件触发时间及时间偏移的方法重载,支持传入 time
类型的参数来设置事件触发时间,以timeZone
来设置时间偏移。不传入该参数,则取 track
被调用时的本机时间以及偏移作为事件触发时间以及时区偏移。
注意: 尽管事件可以设置触发时间,但是接收端会做如下的限制,只接收相对服务器时间在前 10 天至后 3 天的数据,超过时限的数据将会被视为异常数据,整条数据无法入库。
自 iOS SDK v2.3.1 版本开始,您可以通过设置 SDK 默认时区的方式,对齐多个时区下的事件时间,请参考iOS SDK 使用指南 设置默认时区小节。自 iOS 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
这一计时属性将会被记录在事件中
4.用户属性
TA平台目前支持的用户属性设置接口为 userSet
、userSetOnce
、userAdd
、userUnset
、userDel
与 userAppend
a) userSet
对于一般的用户属性,您可以调用 userSet
来进行设置,使用该接口上传的属性将会覆盖原有的属性值,如果之前不存在该用户属性,则会新建该用户属性,类型与传入属性的类型一致
RNThinkingAnalyticsModule.userSet({"appid": "YOUR_APPID",
"properties":{"usersetkey":2,"usersetkey2":"usersetvalue"}})
b) userSetOnce
如果您要上传的用户属性只要设置一次,则可以调用 userSetOnce
来进行设置,当该属性之前已经有值的时候,将会忽略这条信息。
RNThinkingAnalyticsModule.userSetOnce({"appid": "YOUR_APPID",
"properties":{"name":"yea"}})
c) userAdd
当您要上传数值型的属性时,您可以调用 userAdd
来对该属性进行累加操作,如果该属性还未被设置,则会赋值 0 后再进行计算
RNThinkingAnalyticsModule.userAdd({"appid": "YOUR_APPID",
"properties":{"age":1}})
d) userUnset
当您要清空用户的某个用户属性值时,您可以调用 userUnset:
来对指定属性进行清空操作,如果该属性还未在集群中被创建,则 userUnset:
不会创建该属性
RNThinkingAnalyticsModule.userUnset({"appid": "YOUR_APPID",
"properties":"usersetkey"})
e) userDel
如果您要删除某个用户,可以调用 userDel
将这名用户删除,您将无法再查询该名用户的用户属性,但该用户产生的事件仍然可以被查询到
RNThinkingAnalyticsModule.userDel({"appid": "YOUR_APPID"})
f) userAppend
从 iOS SDK v2.4.0 版本开始,您可以调用 userAppend
对 Array 类型的用户属性进行追加操作。
RNThinkingAnalyticsModule.userAppend({"appid": "YOUR_APPID",
"properties":{"key":["age","2"]}})
5. 自动采集事件
关于自动采集事件的具体使用方法,请参考 iOS SDK 自动采集指南一章。
RN 中的调用方法如下:
RNThinkingAnalyticsModule.enableAutoTrack({"appid": "YOUR_APPID",
"autoTrackType": {"appStart": true,
"appEnd": true,
"appViewCrash": true,
"appInstall": true}})
6. SDK配置
a) 暂停/停止数据上报
在 iOS SDK v2.1.0 版本中,新增了停止 SDK 上报数据的功能,一共有两类停止 SDK 上报的接口:
1. 暂停 SDK 上报(enableTracking)
您可能希望在一些场景下,暂时停止 SDK 的数据采集以及上报,比如用户处于测试环境中、或者用户登录了一个测试账号,此时您可以调用下列接口,暂时停止 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 默认会使用本机时间作为事件发生时间上报,如果用户手动修改设备时间会影响到您的业务分析,自 iOS 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 服务进行时间校准存在一定的不确定性,建议您优先考虑用时间戳校准的方式。
除了以上校准时间接口外,在 iOS 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": "UPDATABLE_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
- 代码优化
v2.0.0 2020/05/25
- 新增 API 接口
- 支持多实例
- 支持自动采集事件(新增 APP 安装事件,启动事件,关闭事件,崩溃事件)
- 支持客户端 SDK 的时间校准功能
- 新增 optOutTracking/optInTracking 接口
- 新增 enableTracking 接口, 可以打开或关闭实例上报功能
- 支持事件和用户属性数据上报
- 支持公共事件属性