目录
此内容是否有帮助?

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

← Android SDK Weex 框架支持 →