MacOS SDK 使用指南

提示

在接入前, 请先阅读接入前准备。

您可以在 GitHub (opens new window) 获取 MacOS SDK 源码。

MacOS SDK 要求最低系统版本为 OSX 10.10

最新版本为: 1.0.0

更新时间为: 2022-07-18

一、集成与初始化 SDK

1.1 自动集成 SDK

• 使用 CocoaPods 安装 SDK

1.创建并编辑 Podfile 内容（如果已有，直接编辑）：

创建 Podfile，项目工程（.xcodeproj）文件同目录下命令行执行命令：

pod init

编辑 Podfile 的内容如下：

platform :ios, '9.0'
target 'YourProjectTarget' do
  pod 'ThinkingSDKMacOS'
end

SDK 支持在 AppExtension 中进行数据采集。

如果您的项目存在 AppExtension，那么编辑 Podfile 的内容如下：

target 'YourAppExtensionTarget' do
  pod "ThinkingSDKMacOS/Extension"
end

2.执行安装命令

pod install

成功以后，会出现如下记录：

3.导入成功，启动工程

命令执行成功后，会生成 .xcworkspace 文件，说明您已成功导入 SDK。打开 .xcworkspace 文件以启动工程（注意：此时不能同时开启 .xcodeproj 文件）

1.2 初始化 SDK

新增多 APP ID 实例的特性，关于多 APPID 的使用指南，请参考 iOS SDK 多 APPID 指南一节

在 AppDelegate.m 中添加 #import <ThinkingSDKMacOS/ThinkingAnalyticsSDK.h>

然后在 application:didFinishLaunchingWithOptions: 中添加初始化

如下

// 初始化
ThinkingAnalyticsSDK *instance = [ThinkingAnalyticsSDK startWithAppId:APP_ID withUrl:SERVER_URL];

// 支持初始化多个APPID实例
// ThinkingAnalyticsSDK *instance2 = [ThinkingAnalyticsSDK startWithAppId:APP_ID2 withUrl:SERVER_URL2];

// 初始化
let instance = ThinkingAnalyticsSDK.start(withAppId: "YOUR_APPID", withUrl: "YOUR_SERVER_URL")

// 支持初始化多个APPID实例
// let instance2 = ThinkingAnalyticsSDK.start(withAppId: "YOUR_APPID2", withUrl: "YOUR_SERVER_URL2")

参数 APP_ID 是您的项目的 APP_ID ，在您申请项目时会给出，请在此处填入

参数 SERVER_URL 为数据上传的 URL

如果您使用的是云服务，请输入以下 URL:

https://global-receiver-ta.thinkingdata.cn

如果您使用的是私有化部署的版本，请输入以下 URL:

https://数据采集地址

使用 https 协议，请自行申请具有 SSL 证书的域名，TA 工作人员将会协助进行端口配置。

在完成初始化后，您可以按以下方式来使用 SDK ：

// 后续可以通过如下两种方法使用 SDK
[instance track:@"event_name" properties:eventProperties];
// [[ThinkingAnalyticsSDK sharedInstanceWithAppid:APP_ID] track:@"event_name" properties:eventProperties];

// v1.2.0版本之前，或者单实例可使用下列使用 SDK
// [[ThinkingAnalyticsSDK sharedInstance] track:@"event_name" properties:eventProperties];

// 后续可以通过如下两种方法使用 SDK
let properties:Dictionary<String,String>=["key":"value"];
instance.track("event_name", properties:properties)

// 单实例可使用下列使用 SDK
// ThinkingAnalyticsSDK.sharedInstance(withAppid: "YOUR_APPID").track("event_name", properties:eventProperties)

新增实例名特性，在实例初始化时传入实例名称 name ，用于标识实例。您也可以根据实例名称 name 获取实例。

// 为实例设置 name
TDConfig *config = [[TDConfig alloc] initWithAppId:@"YOUR_APPID" serverUrl:@"YOUR_SERVER_URL"];
config.name = @"YOUR_NAME";
[ThinkingAnalyticsSDK startWithConfig:config];

// 根据name获取实例
ThinkingAnalyticsSDK *instance = [ThinkingAnalyticsSDK sharedInstanceWithAppid: @"YOUR_NAME"];

// 为实例设置 name
let config = TDConfig.init(appId: "YOUR_APPID", serverUrl: "YOUR_SERVER_URL")
config.name = "YOUR_NAME"
ThinkingAnalyticsSDK.start(with: config)

// 根据 name 获取实例
let instance = ThinkingAnalyticsSDK.sharedInstance(withAppid: "YOUR_NAME")

1.3 后台自启事件说明

通过 trackRelaunchedInBackgroundEvents 来配置，YES 表示采集，NO 表示不采集。

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // ...
    TDConfig *config = [[TDConfig alloc] init];
    config.launchOptions = launchOptions;
    config.trackRelaunchedInBackgroundEvents = YES;
    ThinkingAnalyticsSDK *instance = [ThinkingAnalyticsSDK startWithAppId:@"YOUR_APPID" withUrl:@"YOUR_SERVER_URL" withConfig:config];
    return YES;
}

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

    let config = TDConfig()
    config.launchOptions = launchOptions ?? [:]
    config.trackRelaunchedInBackgroundEvents = true
    ThinkingAnalyticsSDK.start(withAppId: "APP_ID", withUrl: "SERVICE_URL", with: config)

    return true
}

1.4 AppExtension 事件采集

支持在 AppExtension 中进行事件采集。

在 AppExtension 中初始化专用事件采集模块：

// 如果需要时间校准，请开启这一行代码
[TAAppExtensionAnalytic calibrateTimeWithNtp:@"time.apple.com"];

// 初始化
NSString *token = @"您的事件采集类的唯一标识，一般为appid";
NSString *appGroupId = @"您的应用组标识";
TAAppExtensionAnalytic *analytic = [TAAppExtensionAnalytic analyticWithInstanceName:token appGroupId:appGroupId];

AppExtension 中的事件采集操作：

[analytic writeEvent:@"event_name" properties:@{@"property_key": @"value"}];

AppExtension 中的事件采集，只做记录，不会上报，数据存储在 AppGroup 的共享存储中。所以需要在主 App 启动时，从共享存储获取数据，并进行上报。在主 App 启动完成，且 SDK 初始化完成后，调用如下代码：

NSString *token = @"您的事件采集类的唯一标识，一般为appid";
ThinkingAnalyticsSDK *instance = [ThinkingAnalyticsSDK sharedInstanceWithAppid:token];
    
NSString *appGroupId = @"您的应用组标识";
[instance trackFromAppExtensionWithAppGroupId:appGroupId];

二、设置用户 ID

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

2.1 设置访客 ID（可选）

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

[instance identify:@"123ABCabc"];

instance.identify("123ABCabc")

如果您需要替换访客 ID ，则应当在初始化 SDK 结束之后立即进行调用，请勿多次调用，以免产生无用的账号

如果需要获得当前访客 ID，可以调用 getDistinctId 获取：

// 返回访客 ID，多实例的情况下，返回的是调用实例的访客 ID
[instance getDistinctId];

// 返回访客 ID，多实例的情况下，返回的是调用实例的访客 ID
instance.getDistinctId()

2.2 设置账号 ID

在用户进行登录时，可调用 login: 来设置用户的账号 ID， TA 平台优先以账号 ID 作为身份标识，设置后的账号 ID 将会被保存，多次调用 login: 将覆盖先前的账号 ID ：

[instance login:@"123ABCabc@thinkingdata.cn"];

instance.login("123ABCabc@thinkingdata.cn")

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

2.3 清空账号 ID

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

[instance logout];

instance.logout()

我们推荐您在显性的登出事件时调用 logout，比如用户产生注销行为时才调用，不需要在关闭 App 时进行调用。

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

三、发送事件

在 SDK 初始化完成之后，您就可以调用 track:、 track:properties:来上传事件，一般情况下，您可能需要上传 20~100 个不同的事件，如果您是第一次使用 TA 后台，我们推荐您先上传几个关键事件。

3.1 发送事件

您可以调用 track:、 track:properties: 来上传事件，建议您根据先前梳理的文档来设置事件的属性以及发送信息的条件：

// 该事件没有设置属性
[instance track:@"StartApp"];

// 上传购买商品事件
NSDictionary *eventProperties = @{
    @"product_name": @"商品名",
    @"product_num": @(1),
    @"IsFirstBuy": @(YES)
};
[instance track:@"product_buy" properties:eventProperties];

// 该事件没有设置属性
instance.track("StartApp")

// 上传购买商品事件
let properties = [
    "productName": "商品名",
    "productNumber": 1,
    "isFirstBuy": true
] as [String: Any]
ThinkingAnalyticsSDK.sharedInstance()?.track("event_name", properties: properties)

事件的名称是 NSString 类型，只能以字母开头，可包含数字，字母和下划线“_”，长度最大为 50 个字符，对字母大小写不敏感。

• 事件的属性是一个 NSDictionary 对象，其中每个元素代表一个属性。
• Key 的值为属性的名称，为 NSString 类型，规定只能以字母开头，包含数字，字母和下划线“_”，长度最大为 50 个字符，对字母大小写不敏感。
• Value 为该属性的值，可以为 NSString、NSNumber、NSDate、 NSArray、NSDictionary。NSDictionary中的内容可以包含NSString、NSNumber、NSDate 以及 NSArray(其中内容为字符串)； NSArray 中的内容可以包含 NSDictionary 和 NSString
• 如果您需要上传布尔型的属性，则请以 @YES 与 @NO 或 [NSNumber numberWithBool:YES] 与 [NSNumber numberWithBool:NO] 来赋值。

不可以使用 @true、 @false、 @TRUE 和 @FALSE 赋值布尔型数据。

注意:

NSArray 类型，需配合 TA 后台 v2.5 及后续版本使用.

NSDictionary类型，需配合TA后台v3.5及后续版本使用

支持设置事件触发时间及时间偏移的方法重载，支持传入 NSDate类型的参数来设置事件触发时间，以 NSTimeZone 类型的参数来设置时间偏移。不传入该参数，则取 track: 被调用时的本机时间以及偏移作为事件触发时间以及时区偏移：

NSDictionary *properties = @{
    @"product_name": @"商品名",
    @"product_num": @1,
    @"IsFirstBuy": @YES
};
[instance track:@"product_buy"
     properties:properties
           time:[NSDate date]
       timeZone:[NSTimeZone timeZoneWithName:@"Asia/Shanghai"]];

let properties = ["product_name": "商品名", "product_num": NSNumber.init(value: 1), "IsFirstBuy": true] as [String: Any]
instance.track("product_buy", properties:properties time: Date(), timeZone: NSTimeZone(name: "Asia/Shanghai")! as TimeZone)

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

您可以通过设置 SDK 默认时区的方式，对齐多个时区下的事件时间，请参考设置默认时区小节。

您可以通过校准 SDK 时间接口来统一使用服务端时间完成数据采集。请参考校准时间小节。

3.2 设置公共事件属性

对于一些重要的属性，譬如用户的会员等级、来源渠道等，这些属性需要设置在每个事件中，此时您可以将这些属性设置为公共事件属性。公共事件属性指的就是每个事件都会带有的属性，您可以调用 setSuperProperties: 来设置公共属性 ，我们推荐您在发送事件前，先设置公共事件属性。

公共事件属性的格式要求与事件属性一致。

[instance setSuperProperties:@{@"Channel": @"ABC", @"isTest": @YES}];

// 设置后上传数据：
[instance track:@"product_view"
     properties:@{@"product_id": @"A1234"}];

// 相当于在事件中设置了属性：
NSDictionary *properties = @{
    @"Channel": @"ABC",
    @"isTest": @YES,
    @"product_id": @"A1234"
};
[instance track:@"product_view"
     properties:properties];

instance.setSuperProperties(["Channel" : "ABC", "isTest": true])

// 设置后上传数据：
instance.track("product_view", properties: ["product_id" : "A1234"])

// 相当于在事件中设置了属性：
let properties = ["Channel": "ABC", "isTest": true, "product_id": "A1234"] as [String: Any]
instance.track("product_view", properties: properties)

公共事件属性将会被保存到缓存中，无需每次启动 App 时调用。如果调用 setSuperProperties: 设置了先前已设置过的公共事件属性，则会覆盖之前的属性。如果公共事件属性和 track:properties: 上传的某个属性的 Key 重复，则该事件的属性会覆盖公共事件属性：

[instance setSuperProperties:@{@"Channel": @"ABC", @"isTest": @YES}];

// 覆盖"Channel"，此时属性"Channel"的值为"XYZ"
[instance setSuperProperties:@{@"Channel": @"XYZ"}];

// 覆盖"isTest"，"isTest"的值为False
[instance track:@"product_view"
     properties:@{@"isTest": @NO}];

instance.setSuperProperties(["Channel": "ABC", "isTest": true])

// 覆盖"Channel"，此时属性"Channel"的值为"XYZ"
instance.setSuperProperties(["Channel": "XYZ"])

// 覆盖"isTest"，"isTest"的值为False
instance.track("product_view", properties: ["isTest": false])

如果您需要删除某个公共事件属性，可以调用 unsetSuperProperty: 清除指定的公共事件属性；如果您想要清空所有公共事件属性，则可以调用 clearSuperProperties;如果您想要获取所有公共事件属性，可以调用currentSuperProperties;

// 清除一条公共事件属性，将之前设置"isTest"属性清除
[instance unsetSuperProperty:@"isTest"];

// 清除所有公共事件属性
[instance clearSuperProperties];

//获取所有公共属性
[instance currentSuperProperties];

// 清除一条公共事件属性，将之前设置"isTest"属性清除
instance.unsetSuperProperty("isTest")

// 清除所有公共事件属性
instance.clearSuperProperties()

//获取所有公共属性
instance.currentSuperProperties()

3.3 设置动态公共属性

在 v1.2.0 版本中，新增了动态公共属性的特性，即公共属性可以上报时获取当时的值，使得诸如会员等级之类的可变公共属性可以被便捷地上报。通过 registerDynamicSuperProperties 设置动态公共属性类之后，SDK 将会在事件上报时自动执行并获取返回值中的属性，添加到触发的事件中。以下例子是每次上报时将获取当前时间并切换时区，当任意事件触发时，SDK 会将返回的时间加入到该事件的属性中。

// 设置动态公共属性，在事件上报时动态获取事件发生时刻
[instance registerDynamicSuperProperties:^NSDictionary * _Nonnull{
    NSDateFormatter *formatter = [[NSDateFormatter alloc] init];
    [formatter setDateFormat:@"yyyy-MM-dd HH:mm:ss.SSS"];
    formatter.timeZone = [NSTimeZone timeZoneWithName:@"America/Chicago"];
    NSDate *datenow = [NSDate date];
    NSString *currentTimeString = [formatter stringFromDate:datenow];
    return @{@"AmericaTime": currentTimeString};
}];

// 设置动态公共属性，在事件上报时动态获取事件发生时刻
instance.registerDynamicSuperProperties { () -> [String : Any] in
    let formatter = DateFormatter()
    formatter.dateFormat = "yyyy-MM-dd HH:mm:ss.SSS"
    formatter.timeZone = TimeZone(abbreviation: "CDT")
    let currentTimeString = formatter.string(from: Date())
    return ["AmericaTime": currentTimeString]
}

3.4 记录事件时长

如果您需要记录某个事件的持续时长，可以调用 timeEvent 来开始计时，配置您想要计时的事件名称，当您上传该事件时，将会自动在您的事件属性中加入 #duration 这一属性来表示记录的时长，单位为秒。

// 开始计时，记录的事件为 "product_view"
[instance timeEvent:@"product_view"];

//其他代码...

// 上传事件，计时结束，"product_view" 这一事件中将会带有表示事件时长的属性 "#duration"
[instance track:@"product_view"];

// 开始计时，记录的事件为 "product_view"
instance.timeEvent("product_view")

// 其他代码...

// 上传事件，计时结束，"product_view" 这一事件中将会带有表示事件时长的属性 "#duration"
instance.track("product_view")

四、用户属性

TA 平台目前支持的用户属性设置接口为 user_set:、user_setOnce:、user_add:、user_unset:、user_delete与user_append

4.1 user_set

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

// 设置用户属性
[instance user_set:@{@"UserName": @"TA", @"Age": @20}];

// 设置用户属性
instance.user_set(["UserName": "TA", "Age": 20])

属性格式要求与事件属性保持一致。

4.2 user_setOnce

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

// 设置用户名
[instance user_setOnce:@{@"UserName": @"TA"}];
// 此时用户名为TA

[instance user_setOnce:@{@"UserName": @"ABC"}];
// 此时用户名仍为TA，此条数据被忽略

// 设置用户名
instance.user_setOnce(["UserName": "TA"])
// 此时用户名为TA

instance.user_setOnce(["UserName": "ABC"])
// 此时用户名仍为TA，此条数据被忽略

属性格式要求与事件属性保持一致。

4.3 user_add

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

// 设置累计付费金额
[instance user_add:@{@"TotalRevenue": @6}];
// 此时累计付费值为6

[instance user_add:@{@"TotalRevenue": @30}];
// 此时累计付费值为36

// 设置累计付费金额
instance.user_add(["TotalRevenue": 6])
// 此时累计付费值为6

instance.user_add(["TotalRevenue": 30])
// 此时累计付费值为36

设置的属性key为字符串，Value 只允许为数值。

4.4 user_unset

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

// 清空该用户的累计付费金额属性值
[instance user_unset:@"TotalRevenue"];

// 清空该用户的累计付费金额属性值
instance.user_unset("TotalRevenue")

user_unset传入值为被清空属性的 Key 值。

4.5 user_delete

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

[instance user_delete];

instance.user_delete()

4.6 user_append

您可以调用 user_append 对 NSArray 类型的用户属性进行追加操作。

// 调用 user_append 为用户属性 product_buy 追加元素。如果不存在，会新建该元素
[instance user_append:@{@"product_buy": @[@"product_name1", @"product_name2"]}];

instance.user_append(["product_buy": ["product_name1", "product_name2"]])

4.7 user_uniqAppend

您可以调用 user_uniqAppend 对 NSArray 类型的用户属性进行追加操作。

和 user_append 接口的区别，调用 user_uniqAppend 接口会对追加的用户属性进行去重， user_append 接口不做去重，用户属性可存在重复。

// 调用 user_uniqAppend 为用户属性 product_buy 追加元素。如果不存在，会新建该元素
[instance user_uniqAppend:@{@"product_buy": @[@"product_name1", @"product_name2"]}];

instance.user_uniqAppend(["product_buy": ["product_name1", "product_name2"]])

五、SDK 配置

5.1 设置上传的网络条件

在默认情况下，SDK 将会网络条件为在 2G, 3G, 4G, 5G 及 Wifi 时上传数据，您可以通过下列方法修改允许上传的网络条件：

// 在 2G, 3G, 4G, 5G 及 Wifi 时上传数据
[instance setNetworkType:TDNetworkTypeALL];

// 只在 Wifi 环境下上报数据
[instance setNetworkType:TDNetworkTypeOnlyWIFI];

// 在 2G ,3G, 4G, 5G 及 Wifi 时上传数据, 默认设置
[instance setNetworkType:TDNetworkTypeDefault];

// 在 2G, 3G, 4G 及 Wifi 时上传数据
ThinkingAnalyticsSDK.sharedInstance()?.setNetworkType(ThinkingAnalyticsNetworkType.TDNetworkTypeALL)

// 只在 Wifi 环境下上报数据
ThinkingAnalyticsSDK.sharedInstance()?.setNetworkType(ThinkingAnalyticsNetworkType.TDNetworkTypeOnlyWIFI)

// 在 3G, 4G 及 Wifi 时上传数据, 默认设置
ThinkingAnalyticsSDK.sharedInstance()?.setNetworkType(ThinkingAnalyticsNetworkType.TDNetworkTypeDefault)

5.2 数据上报状态

新增了 SDK 数据上报状态，一共有四种状态：

5.2.1 暂停 SDK 上报（TATrackStatusPause）

您可能希望在一些场景下，暂时停止 SDK 的数据采集以及上报，比如用户处于测试环境中、或者用户登录了一个测试账号，此时您可以调用下列接口，暂时停止 SDK 的上报。

您可以通过某一实例（包括主要实例以及轻实例）调用 setTrackStatus:，传入 TATrackStatusPause 来暂停 SDK 的上报，该实例已经设置的 #distinct_id、#account_id、公共属性等将保留；该实例已经采集但还未上报成功的数据将继续尝试上报；后续该实例不能采集以及上报任何新数据、不能设置访客 ID、账户 ID 以及公共属性等，但是可以读取该实例已经设置的公共属性和设备 ID、访客 ID、账号 ID 等信息。

实例的停止状态将会被保存在本地缓存，直到调用 setTrackStatus: 、传入 TATrackStatusNormal ，SDK 实例将会重新恢复数据采集以及上报，需要注意轻实例因为不进行缓存，因此每次打开 APP 后，轻实例的暂停状态不会被保留，将重新开启上报。

// 暂停上报
[instance setTrackStatus: TATrackStatusPause];

// 恢复上报
[instance setTrackStatus: TATrackStatusNormal];

// 暂停上报
instance.setTrackStatus(.pause)

// 恢复上报
instance.setTrackStatus(.normal)

5.2.2 停止SDK上报并清除缓存（TATrackStatusStop）

在一些特殊场景下，您可能需要完全停止 SDK 的功能，比如在适用 GDPR 的地区，用户选择不提供数据采集权限，则您可以调用如下接口完全关闭 SDK 的功能。

TATrackStatusStop 只能通过主要实例调用，与 TATrackStatusPause 的最大区别在于，其将会清空该实例的本地缓存，包括本实例的访客 ID，账号 ID，公共属性，以及未上报的数据队列。之后再关闭该实例的采集和上报功能。

// 停止上报，并重置本地缓存
[instance setTrackStatus: TATrackStatusStop];

// 停止上报，并重置本地缓存
instance.setTrackStatus(.stop)

实例的停止状态也将保存在本地缓存，直到调用 setTrackStatus: 、传入 TATrackStatusNormal ，后续可以继续上报，但此时相当于一个全新的实例

// 重新开启上报
[instance setTrackStatus: TATrackStatusNormal];

// 重新开启上报
instance.setTrackStatus(.normal)

5.2.3 数据采集入库但暂停上报数据（TATrackStatusSaveOnly）

您可能希望在一些场景下，暂时停止 SDK 数据的网络上报，以免影响用户体验，比如用户处于游戏战斗场景，此时您可以调用下列接口，暂时停止 SDK 的网络上报。

您可以通过某一实例（包括主要实例以及轻实例）调用 setTrackStatus: ，传入 TATrackStatusSaveOnly 来暂停 SDK 的网络上报（数据采集依然存在）；

实例的停止状态将会被保存在本地缓存，直到调用 setTrackStatus: 、传入 TATrackStatusNormal ，SDK 实例将会把本地库中未上报数据立即上报，需要注意轻实例因为不进行缓存，因此每次打开 APP 后，轻实例的暂停状态不会被保留，将重新开启上报。

// 可以采集入库 暂停发送数据
[instance setTrackStatus: TATrackStatusSaveOnly];

// 恢复上报
[instance setTrackStatus: TATrackStatusNormal];

// 可以采集入库 暂停发送数据
instance.setTrackStatus(.saveOnly)

// 恢复上报
instance.setTrackStatus(.normal)

5.2.4 正常状态（TATrackStatusNormal）

SDK 正常状态TATrackStatusNormal，数据会进行采集并网络上报。

SDK不进行数据上报状态设置的话，就是默认此状态。

// 正常状态（默认状态） 可以不进行设置
[instance setTrackStatus: TATrackStatusNormal];

// 正常状态（默认状态） 可以不进行设置
instance.setTrackStatus(.normal)

5.3 打印数据 Log

可以调用setLogLevel来开启（默认是关闭的）：

[ThinkingAnalyticsSDK setLogLevel:TDLoggingLevelDebug];
// TDLoggingLevelError :Error Log
// TDLoggingLevelInfo  :Info  Log
// TDLoggingLevelDebug :Debug Log

ThinkingAnalyticsSDK.setLogLevel(TDLoggingLevel.debug)
// TDLoggingLevel.error :Error Log
// TDLoggingLevel.info  :Info  Log
// TDLoggingLevel.debug :Debug Log

5.4 获取设备 ID

加入了获取设备 ID（也就是预置属性#device_id）的接口，您可以通过调用 getDeviceId 来获取设备 ID：

[instance getDeviceId];

 // 如果需要将设备ID设置成访客ID可以如下调用
 // [instance identify:[instance getDeviceId]];

5.5 配置 HTTPS 校验方法:

SDK 可以配置 HTTPS 校验方法，需要在初始化的时候首先获取 TDConfig 实例，然后用 TDConfig 完成初始化。

 TDConfig *config = [[TDConfig alloc] init];
 TDSecurityPolicy *securityPolicy = [TDSecurityPolicy policyWithPinningMode:TDSSLPinningModeNone];
 // TDSSLPinningModeNone:默认认证方式，只会在系统的信任的证书列表中对服务端返回的证书进行验证
 // TDSSLPinningModePublicKey:校验证书的公钥
 // TDSSLPinningModeCertificate:校验证书的所有内容
 securityPolicy.allowInvalidCertificates = YES; // 是否允许自建证书或者过期SSL证书，默认NO
 securityPolicy.validatesDomainName = NO; // 是否验证证书域名，默认YES
 config.securityPolicy = securityPolicy;
 [ThinkingAnalyticsSDK startWithAppId:@"YOUR_APPID" withUrl:@"YOUR_SERVER_URL" withConfig:config];

let tdconfig = TDConfig();
let tdSecurityPolicy = TDSecurityPolicy(pinningMode: TDSSLPinningMode.publicKey);
// TDSSLPinningMode [] 默认认证方式，只会在系统的信任的证书列表中对服务端返回的证书进行验证
// TDSSLPinningMode.publicKey 校验证书的公钥
// TDSSLPinningMode.certificate 校验证书的所有内容
tdSecurityPolicy.allowInvalidCertificates = true // 是否允许自建证书或者过期SSL证书，默认NO
tdSecurityPolicy.validatesDomainName = false // 是否验证证书域名，默认YES
tdconfig.securityPolicy = tdSecurityPolicy;
ThinkingAnalyticsSDK.start(withAppId: "YOUR_APPID", withUrl: "YOUR_SERVER_URL", with: tdconfig);

5.6 设置默认时区

默认情况下，如果用户不指定事件发生时间，SDK 默认会使用接口调用时的本机时间作为事件发生时间上报。自 v2.3.1 版本开始，您也可以通过设置默认时区接口，指定默认的时区，这样所有的事件（包括自动采集事件）都将按照您设置的时区来对齐事件时间：

// 获取 TDConfig 实例
TDConfig *config = [[TDConfig alloc] init];
// 设置默认时区为 UTC
config.defaultTimeZone = [NSTimeZone timeZoneWithName:@"UTC"];
// 初始化 SDK
ThinkingAnalyticsSDK *instance = [ThinkingAnalyticsSDK startWithAppId:@"YOUR_APPID" withUrl:@"YOUR_SERVER_URL" withConfig:config];

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

5.7 开启 Debug 模式

客户端 SDK 支持 Debug 模式，需要配合 TA 平台 2.5 之后的版本使用。

Debug 模式可能会影响数据采集质量和 App 的稳定性，只用于集成阶段数据验证，不要在线上环境使用。

当前 SDK 实例支持三种运行模式，在 TDConfig 中定义：

/**
Debug模式

- ThinkingAnalyticsDebugOff : 默认 不开启Debug模式
*/
typedef NS_OPTIONS(NSInteger, ThinkingAnalyticsDebugMode) {
    /**
     默认 不开启Debug模式
     */
    ThinkingAnalyticsDebugOff      = 0,

    /**
     开启Debug_only模式，只对数据做校验，不会入库
     */
    ThinkingAnalyticsDebugOnly     = 1 << 0,

    /**
     Debug 模式，数据逐条上报。当出现问题时会以日志和异常的方式提示用户
     */
    ThinkingAnalyticsDebug         = 1 << 1
};

为了设置 SDK 实例运行模式，请使用 TDConfig 来完成 SDK 初始化：

// 获取 TDConfig 实例
TDConfig *config = [[TDConfig alloc] init];
// 设置运行模式为 Debug 模式
config.debugMode = ThinkingAnalyticsDebug;
// 初始化 SDK
ThinkingAnalyticsSDK *instance = [ThinkingAnalyticsSDK startWithAppId:@"YOUR_APPID" withUrl:@"YOUR_SERVER_URL" withConfig:config];

为了避免 Debug 模式在生产环境上线，规定只有指定的设备才能开启 Debug 模式。只有在客户端开启了 Debug 模式，并且设备 ID 在 TA 后台的"埋点管理"页的"Debug 数据"板块中配置了的设备才能开启 Debug 模式。

设备 ID 可以通过以下三种方式获取：

• TA 平台中事件数据中的 #device_id 属性
• 客户端日志：SDK 初始化完成后会打印设备 DeviceId
• 通过实例接口调用：获取设备 ID

5.8 校准时间

SDK 默认会使用本机时间作为事件发生时间上报，如果用户手动修改设备时间会影响到您的业务分析，您可以使用从服务端获取的当前时间戳对 SDK 的时间进行校准。此后，所有为指定时间的调用，包括事件数据和用户属性设置操作，都会使用校准后的时间作为发生时间。

// 1585633785954 为当前 unix 时间戳，单位为毫秒，对应北京时间 2020-03-31 13:49:45
[ThinkingAnalyticsSDK calibrateTime:1585633785954];

// 1585633785954 为当前 unix 时间戳，单位为毫秒，对应北京时间 2020-03-31 13:49:45
ThinkingAnalyticsSDK.calibrateTime(1585633785954)

我们也提供了从 NTP 获取时间对 SDK 校准的功能。您需要传入您的用户可以访问的 NTP 服务器地址。之后 SDK 会尝试从传入的 NTP 服务地址中获取当前时间，并对 SDK 时间进行校准。如果在默认的超时时间（3 秒）之内，未获取正确的返回结果，后续将使用本地时间上报数据。

// 使用苹果公司 NTP 服务对时间进行校准
[ThinkingAnalyticsSDK calibrateTimeWithNtp:@"time.apple.com"];

ThinkingAnalyticsSDK.calibrateTime(withNtp: "time.apple.com")

注意：

• 您需要谨慎地选择您的 NTP 服务器地址，以保证网络状况良好的情况下，用户设备可以很快的获取到服务器时间。
• 使用 NTP 服务进行时间校准存在一定的不确定性，建议您优先考虑用时间戳校准的方式。

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

六、相关预置属性

6.1 所有事件带有的预置属性

以下预置属性，是 SDK 中所有事件都会带有的预置属性

属性名	中文名	说明
#ip	IP 地址	用户的 IP 地址，TA 将以此获取用户的地理位置信息
#country	国家	用户所在国家，根据 IP 地址生成
#country_code	国家代码	用户所在国家的国家代码(ISO 3166-1 alpha-2，即两位大写英文字母)，根据 IP 地址生成
#province	省份	用户所在省份，根据 IP 地址生成
#city	城市	用户所在城市，根据 IP 地址生成
#os_version	操作系统版本	iOS 11.2.2、Android 8.0.0 等
#manufacturer	设备制造商	用户设备的制造商，如 Apple，vivo 等
#os	操作系统	如 Android、iOS 等
#device_id	设备 ID	用户的设备 ID，iOS 取用户的 IDFV 或 UUID，Android 取 androidID
#device_model	设备型号	用户设备的型号，如 iPhone 8 等
#app_version	APP 版本	您的 APP 的版本
#bundle_id	应用唯一标识	应用包名或进程名
#lib	SDK 类型	您接入 SDK 的类型，如 Android，iOS 等
#lib_version	SDK 版本	您接入 SDK 的版本
#network_type	网络状态	上传事件时的网络状态，如 WIFI、3G、4G 等
#zone_offset	时区偏移	数据时间相对 UTC 时间的偏移小时数
#install_time	程序安装时间	用户安装应用的时间，值来源于系统
#system_language	系统语言	用户设备的系统语言(ISO 639-1，即两位小写英文字母)，如 zh, en 等

6.2 其他预置属性

除了上述提到预置属性，还有部分预置属性需要调用对应接口才会被记录：

属性名	中文名	说明
#duration	事件时长	需要调用计时功能接口 timeEvent: ，记录事件发生时长，单位是秒
#background_duration	后台停留时长	需要调用计时功能接口 timeEvent ，记录事件发生区间内，应用在后台的停留时长，单位是秒

6.3 获取预置属性

可以调用 getPresetProperties 方法获取预置属性。

服务端埋点需要 App 端的一些预置属性时，可以通过此方法获取 App 端的预置属性，再传给服务端。

//获取属性对象
TDPresetProperties *presetProperties = [instance getPresetProperties];

//生成事件预置属性
NSDictionary *properties = [presetProperties toEventPresetProperties];
/*
   {
        "#os": "iOS",
        "#device_id": "A8B1C00B-A6AC-4856-8538-0FBC642C1BAD",
        "#bundle_id": "com.sw.thinkingdatademo",
        "#manufacturer": "Apple",
        "#device_model": "iPhone7",
        "#system_language": "zh",
        "#os_version": "10",
        "#network_type": "WIFI",
        "#zone_offset": 8,
        "#app_version":"1.0.0"
    }
*/

//获取某个预置属性
NSString *bundle_id = presetProperties.bundle_id;//包名
NSString *os = presetProperties.os;//os类型，如iOS
NSString *system_language = presetProperties.system_language;//手机系统语言类型
NSString *os_version = presetProperties.os_version;//系统版本号
NSNumber *zone_offset = presetProperties.zone_offset;//时区偏移
NSString *app_version = presetProperties.app_version;//app版本号

let presetProperties = instance.getPresetProperties();

//生成事件预置属性
let properties = presetProperties.toEventPresetProperties();

//获取某个预置属性
let bundle_id = presetProperties.bundle_id;//包名
let os = presetProperties.os;//os类型，如iOS
let system_language = presetProperties.system_language;//手机系统语言类型
let os_version = presetProperties.os_version;//系统版本号
let zone_offset = presetProperties.zone_offset;//时区偏移值
let app_version = presetProperties.app_version;//app版本号

IP，国家城市信息由服务端解析生成，客户端不提供接口获取这些属性

6.4 预制属性开关

SDK 支持屏蔽指定预制属性的上报。

在工程的info.plist文件中添加TDDisPresetProperties字段，类型是Array，添加的字段对应的预置属性将不会上传。

如屏蔽"#fps", @"#ram", @"#disk", @"#start_reason", @"#simulator"等预制属性，配置如下图：

七、进阶功能

SDK 支持上报三种特殊类型事件: 首次事件、可更新事件、可重写事件。这三种事件需要配合 TA 系统 2.8 及之后的版本使用。由于特殊事件只在某些特定场景下适用，所以请在数数科技的客户成功和分析师的帮助下使用特殊事件上报数据。

7.1 首次事件

首次事件是指针对某个设备或者其他维度的 ID，只会记录一次的事件。例如在一些场景下，您可能希望记录在某个设备上第一次发生的事件，则可以用首次事件来上报数据。

// 示例：上报设备首次事件, 假设事件名为 DEVICE_FIRST
TDFirstEventModel *firstModel = [[TDFirstEventModel alloc] initWithEventName:@"DEVICE_FIRST"];

// 可选参数
firstModel.properties = @{};
[firstModel configTime:[NSDate date] timeZone:[NSTimeZone localTimeZone]];

// 上报事件API
[[ThinkingAnalyticsSDK sharedInstance] trackWithEventModel:firstModel];

// 示例：上报设备首次事件, 假设事件名为 DEVICE_FIRST
let firstModel = TDFirstEventModel(eventName:"DEVICE_FIRST")
// 可选参数
firstModel.properties = ["KEY": "VALUE"]
firstModel.configTime(Date(), timeZone: NSTimeZone.local)
// 上报事件API
ThinkingAnalyticsSDK.sharedInstance()?.track(with: firstModel)

如果您希望以设备以外的其他维度来判断是否首次，则可以为首次事件设置 FIRST_CHECK_ID. 例如您需要记录某个账号的首次事件，可以将账号 ID 设置为首次事件的 FIRST_CHECK_ID:

// 自定义#first_check_id的构造方法
TDFirstEventModel *firstModel = [[TDFirstEventModel alloc] initWithEventName:@"DEVICE_FIRST" firstCheckID:@"YOUR_ACCOUNT_ID"];

// 可选参数
firstModel.properties = @{};
[firstModel configTime:[NSDate date] timeZone:[NSTimeZone localTimeZone]];

// 上报事件API
[[ThinkingAnalyticsSDK sharedInstance] trackWithEventModel:firstModel];

// 示例：上报设备首次事件, 假设事件名为 DEVICE_FIRST
let firstModel = TDFirstEventModel(eventName:"DEVICE_FIRST", firstCheckID:"YOUR_ACCOUNT_ID")
// 可选参数
firstModel.properties = ["KEY": "VALUE"]
firstModel.configTime(Date(), timeZone: NSTimeZone.local)
// 上报事件API
ThinkingAnalyticsSDK.sharedInstance()?.track(with: firstModel)

注意：由于在服务端完成对是否首次的校验，首次事件会延时 1 小时入库。

7.2 可更新事件

您可以通过可更新事件实现特定场景下需要修改事件数据的需求。可更新事件需要指定标识该事件的 ID，并在创建可更新事件对象时传入。TA 后台将根据事件名和事件 ID 来确定需要更新的数据。

// 示例： 上报可被更新的事件，假设事件名为 UPDATABLE_EVENT
TDUpdateEventModel *updateModel = [[TDUpdateEventModel alloc] initWithEventName:@"UPDATABLE_EVENT" eventID:@"test_event_id"];
updateModel.properties = @{@"status": @3, @"price": @100};
// 上报后事件属性 status 为 3, price 为 100
[[ThinkingAnalyticsSDK sharedInstance] trackWithEventModel:updateModel];

TDUpdateEventModel *updateModel_new = [[TDUpdateEventModel alloc] initWithEventName:@"UPDATABLE_EVENT" eventID:@"test_event_id"];
updateModel_new.properties = @{@"status": @5};
// 上报后事件属性 status 被更新为 5, price 不变
[[ThinkingAnalyticsSDK sharedInstance] trackWithEventModel:updateModel_new];

// 示例： 上报可被更新的事件，假设事件名为 UPDATABLE_EVENT
let updateModel = TDUpdateEventModel(eventName: "UPDATABLE_EVENT", eventID: "test_event_id")
updateModel.properties = ["status": 3, "price": 100]

// 可选参数
updateModel.configTime(<#T##time: Date##Date#>, timeZone: <#T##TimeZone?#>)

// 上报后事件属性 status 为 3, price 为 100
ThinkingAnalyticsSDK.sharedInstance()?.track(with: updateModel)


let updateModel_new =TDUpdateEventModel(eventName: "UPDATABLE_EVENT", eventID: "test_event_id")
updateModel_new.properties = ["status": 5]
// 上报后事件属性 status 为 5, price 不变
ThinkingAnalyticsSDK.sharedInstance()?.track(with: updateModel_new)

7.3 可重写事件

可重写事件与可更新事件类似，区别在于可重写事件会用最新的数据完全覆盖历史数据，从效果上看相当于删除前一条数据，并入库最新的数据。TA 后台将根据事件名和事件 ID 来确定需要更新的数据。

// 示例： 上报可被重写的事件，假设事件名为 OVERWRITE_EVENT
TDOverwriteEventModel *overwriteModel = [[TDOverwriteEventModel alloc] initWithEventName:@"OVERWRITE_EVENT" eventID:@"test_event_id"];
overwriteModel.properties = @{@"status": @3, @"price": @100};
// 上报后事件属性 status 为 3, price 为 100
[[ThinkingAnalyticsSDK sharedInstance] trackWithEventModel:overwriteModel];

TDOverwriteEventModel *overwriteModel_new = [[TDOverwriteEventModel alloc] initWithEventName:@"OVERWRITE_EVENT" eventID:@"test_event_id"];
overwriteModel_new.properties = @{@"status": @5};
// 上报后事件属性 status 为 5, price属性被删除
[[ThinkingAnalyticsSDK sharedInstance] trackWithEventModel:overwriteModel_new];

// 示例： 上报可被重写的事件，假设事件名为 OVERWRITE_EVENT
let overwriteModel = TDOverwriteEventModel(eventName: "OVERWRITE_EVENT", eventID: "test_event_id")
overwriteModel.properties = ["status": 3, "price": 100]

// 可选参数
overwriteModel.configTime(<#T##time: Date##Date#>, timeZone: <#T##TimeZone?#>)

// 上报后事件属性 status 为 3, price 为 100
ThinkingAnalyticsSDK.sharedInstance()?.track(with: overwriteModel)


let overwriteModel_new = TDOverwriteEventModel(eventName: "UPDATABLE_EVENT", eventID: "test_event_id")
overwriteModel_new.properties = ["status": 5]
// 上报后事件属性 status 为 5, price 被删除
ThinkingAnalyticsSDK.sharedInstance()?.track(with: overwriteModel_new)

ChangeLog

v1.0.0 2022/07/18

• 支持TA事件采集