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