# iOS SDK Weex 框架支持

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

最新版本为:2.0.0

更新时间为:2020-06-06

# 一、集成 SDK

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

(1) 集成 iOS SDK 请参见iOS SDK 使用指南

(2) 完成 iOS SDK 的集成后,请点此下载 (opens new window)Weex 支持文件,解压后将WeexThinkingDataAnalyticsModule.h 与 WeexThinkingDataAnalyticsModule.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 使用指南

(3) 在 AppDelegate.m 中添加在 AppDelegate.m 中添加

#import "WeexThinkingDataAnalyticsModule.h"

然后在 application:didFinishLaunchingWithOptions: 方法中,在 iOS SDK 与 Weex 初始化的代码之后,添加 Weex 支持插件的初始化代码


-(BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // 初始化 iOS SDK
    [ThinkingAnalyticsSDK startWithAppId:@"APP_ID"
                                   withUrl:@"SERVER_URL"];
    // 初始化 weex
    [WeexSDKManager setup];
    // 初始化 Weex 支持插件
    [WXSDKEngine registerModule:@"WeexThinkingDataAnalyticsModule" withClass:[WeexThinkingDataAnalyticsModule class]];
    return YES;
}

# 1.2 在 JS 文件中获取模块

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

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

# 1.3 在 Weex 中使用 SDK 功能

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

# 二、设置用户 ID

# 2.1 设置访客 ID (可选)

SDK 实例会使用随机 UUID 作为每个用户的默认访客 ID,该 ID 将会作为用户在未登录状态下身份识别 ID。需要注意的是,访客 ID 在用户重新安装 App 以及更换设备时将会变更。

如果用户在您的产品中可以未登录状态下使用,且您需要配置用户在未登录状态下的访客 ID ,则您可以调用 identify 来进行设置:

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。

如果您在 iOS SDK 调用了 login 接口设置了账号 ID,则 RN 中的调用将会覆盖先前设置的账号 ID,同样 iOS SDK 后续的 login 调用也会覆盖 RN 设置的账号 ID

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

# 2.3 清空账号 ID

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

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

在 RN 中的调用 logout 也将清除 iOS SDK 中的账号 ID,同样 iOS SDK 调用 logout 也会清除 RN 中的账号 ID

我们推荐您在显性的登出事件时调用 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 为该事件的所有属性,在 iOS SDK v2.2.0 版本中加入了设置事件触发时间及时间偏移的方法重载,支持传入 time 类型的参数来设置事件触发时间,以timeZone 来设置时间偏移。不传入该参数,则取 track 被调用时的本机时间以及偏移作为事件触发时间以及时区偏移。

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

自 iOS SDK v2.3.1 版本开始,您可以通过设置 SDK 默认时区的方式,对齐多个时区下的事件时间,请参考iOS SDK 使用指南设置默认时区小节。自 iOS 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 中设置的计时可记录 iOS SDK 上传的对应事件,同样 iOS SDK 设置的计时可记录 RN 中上传的对应事件

# 四、用户属性

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

# 4.1 userSet

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

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

# 4.2 userSetOnce

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

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

# 4.3 userAdd

当您要上传数值型的属性时,您可以调用 userAdd 来对该属性进行累加操作,如果该属性还未被设置,则会赋值 0 后再进行计算

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

# 4.4 userUnset

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

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

# 4.5 userDel

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

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

# 4.6 userAppend

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

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

# 五、自动采集事件

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

RN 中的调用方法如下:

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

# 六、SDK 配置

# 6.1 暂停/停止数据上报

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

# 6.1.1 暂停 SDK 上报(enableTracking)

您可能希望在一些场景下,暂时停止 SDK 的数据采集以及上报,比如用户处于测试环境中、或者用户登录了一个测试账号,此时您可以调用下列接口,暂时停止 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 默认会使用本机时间作为事件发生时间上报,如果用户手动修改设备时间会影响到您的业务分析,自 iOS 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 服务进行时间校准存在一定的不确定性,建议您优先考虑用时间戳校准的方式。

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

注意:用指定时区对齐事件时间,会丢掉设备本机时区信息。如果需要保留设备本机时区信息,目前需要您自己为事件添加相关属性。

# ChangeLog

# v2.0.0 2020/06/06

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