iOS

提示

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

iOS SDK 要求最低系统版本为iOS 8.0

iOS SDK ( Framework 格式) 大小约为 8.1MB

稳定版本为: v2.8.3.2

更新时间为: 2023-04-03

资源下载: SDK (opens new window)，源代码 (opens new window)

Beta版本为: v2.8.4-beta.4 下载 (opens new window)

一、集成 SDK

1.1 自动集成

• 使用 CocoaPods 安装 SDK

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

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

pod init

编辑 Podfile 的内容如下：

platform :ios, '9.0'
target 'YourProjectTarget' do
  pod 'ThinkingSDK'  #ThinkingSDK
end

2.在项目的根目录，执行安装命令

pod install

成功以后，终端会出现如下提示：

3.导入成功，启动工程

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

• 使用Carthage方式安装SDK

1.在 Cartfile 文件中添加以下配置：

github "ThinkingDataAnalytics/ios-sdk"

2.执行 carthage update --platform iOS 并将 ThinkingSDK.framework 添加到您的项目中

1.2 手动集成

1.下载并解压 iOS SDK (opens new window)

2.将 ThinkingSDK.framework拖入 XCode Project Workspace 工程项目中

3.找到Targets,在Build Settings菜单的 Other linker flags 选项添加 -ObjC

4.切换到 Build Phases 选项卡，在 Link Binary With Libraries 栏目下添加如下依赖项：

libz.dylib、Security.framework、SystemConfiguration.framework、libsqlite3.tbd

二、 初始化

//在主线程中初始化SDK
// 方式一
ThinkingAnalyticsSDK *instance = [ThinkingAnalyticsSDK startWithAppId:APPID withUrl:SERVER_URL];
//方式二
TDConfig *config = [[TDConfig alloc]initWithAppid:APPID serverUrl:SERVER_URL];
ThinkingAnalyticsSDK *instance = [ThinkingAnalyticsSDK startWithConfig: config];

//在主线程中初始化SDK
// 方式一
let instance = ThinkingAnalyticsSDK.start(withAppId: APPID, withUrl: SERVER_URL)
//方式二
let config = TDConfig(appid: APPID, serverUrl: SERVER_URL)
let instance = ThinkingAnalyticsSDK.start(with: config)

参数说明:

• APPID: 是您的项目的 APPID，可通过在 TE 后台项目管理页面获取
• SERVER_URL: 为数据上传的 URL
  • 如果您对接的是云服务，填入: https://global-receiver-ta.thinkingdata.cn
  • 如果您使用私有化部署版本，请为数据采集地址绑定域名，并配置 HTTPS 证书：https://数据采集地址绑定域名

三、 常用功能

在使用常用功能之前，建议你先了解用户识别规则；SDK默认会使用设备ID_安装次数作为访客ID，并持久化存储访客ID在本地；用户未登录之前，会以访客ID作为身份识别ID。注意:访客 ID 在用户重新安装 App 以及更换设备时将会变更。

3.1 设置账号ID

在用户进行登录时，可调用 login: 来设置用户的账号 ID， TA 平台将会以账号 ID 作为身份识别 ID，并且设置的账号 ID 将会在调用 logout 之前一直保留。多次调用 login: 将覆盖先前的账号 ID 。

// 用户的登录唯一标识，此数据对应上报数据里的#account_id，此时#account_id的值为TA
[instance login:@"TA"];

// 用户的登录唯一标识，此数据对应上报数据里的#account_id，此时#account_id的值为TA
instance.login("TA")

该方法不会上传登录事件

3.2 设置公共事件属性

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

NSMutableDictionary *superProperties = [NSMutableDictionary new];
[superProperties setValue:@"ta" forKey:@"channel"];//字符串
[superProperties setValue:@1 forKey:@"age"];//数字
[superProperties setValue:@YES forKey:@"isSuccess"];//布尔
[superProperties setValue:[NSDate now] forKey:@"birthday"];//时间
[superProperties setValue:@{@"key":@"value"} forKey:@"object"];//对象
[superProperties setValue:@[@{@"key":@"value"}] forKey:@"object_arr"];//对象组
[superProperties setValue:@[@"value"] forKey:@"arr"];//数组
[instance setSuperProperties:superProperties];//设置公共事件属性

var superProperties: [AnyHashable : Any] = [:]
superProperties["channel"] = "ta" //字符串
superProperties["age"] = 1 //数字
superProperties["isSuccess"] = true //布尔
superProperties["birthday"] = Date() //时间
superProperties["object"] = [
    "key": "value"
] //对象
superProperties["object_arr"] = [["key": "value"]] // 对象组
superProperties["arr"] = ["value"] // 数组

//设置公共事件属性
instance.setSuperProperties(superProperties)

公共事件属性将会被保存到缓存中，无需每次启动 App 时调用。如果调用 setSuperProperties: 设置了先前已设置过的公共事件属性，则会覆盖之前的属性。

• 事件的属性是一个 NSDictionary 对象，其中每个元素代表一个属性。
• Key 为该属性的名称，为字符串类型，规定只能以字母开头，包含数字，字母和下划线 "_"，长度最大为 50 个字符，对字母大小写不敏感,TE会统一转化为小写字母
• Value 为该属性的值，支持字符串、数字、布尔、时间、对象、对象组、数组
• 如果您需要上传布尔型的属性，则请以 @YES 与 @NO 或 [NSNumber numberWithBool:YES] 与 [NSNumber numberWithBool:NO] 来赋值。不可以使用 @true、 @false、 @TRUE 和 @FALSE 赋值布尔型数据。

事件属性、用户属性的要求与公共事件属性保持一致

3.3 开启自动采集

以下代码示例开启安装、启动、关闭事件，如果您想详细了解SDK的自动采集能力，可以查看自动采集功能详细介绍

// 开启自动采集事件(安装，启动，关闭事件)
[[ThinkingAnalyticsSDK sharedInstanceWithAppid:APP_ID]enableAutoTrack:ThinkingAnalyticsEventTypeAppInstall | ThinkingAnalyticsEventTypeAppStart |ThinkingAnalyticsEventTypeAppEnd];

3.4 发送事件

您可以调用 track 来上传事件，建议您根据先前梳理的埋点文档来设置事件的属性以及发送信息的条件，此处以用户购买某商品作为范例：

NSDictionary *eventProperties = @{ @"product_name": @"商品名"};
[instance track:@"product_buy" properties:eventProperties];

let properties = ["product_name": "商品名"] as [String: Any]
ThinkingAnalyticsSDK.sharedInstance()?.track("product_buy", properties: properties)

事件的名称是字符串类型，只能以字母开头，可包含数字，字母和下划线 "_"，长度最大为 50 个字符。

3.5 设置用户属性

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

// 设置用户属性
//此时"username"为"ThinkingData"
[instance user_set:@{@"username": @"ThinkingData"}];
//此时"username"为"TA"
[instance user_set:@{@"username": @"TA"}];

// 设置用户属性
//此时"username"为"ThinkingData"
instance.user_set(["usernaame": "ThinkingData"])
//此时"username"为"TA"
instance.user_set(["usernaame": "TA"])

四、最佳实践

以下示例代码包含以上所有操作，我们推荐按照如下步骤使用:

ThinkingAnalyticsSDK *instance;
if (授权隐私政策) {
    instance = ThinkingAnalyticsSDK.sharedInstance(this, TA_APP_ID, TA_SERVER_URL);
    if（instance != null）
    {
      //如果用户已登录，可以设置用户的账号ID作为身份唯一标识
      instance.login("TA");
      
      //设置公共事件属性以后，每个事件都会带有公共事件属性
      NSMutableDictionary *superProperties = [NSMutableDictionary new];
      [superProperties setValue:@"ta" forKey:@"channel"];//字符串
      [superProperties setValue:@1 forKey:@"age"];//数字
      [superProperties setValue:@YES forKey:@"isSuccess"];//布尔
      [superProperties setValue:[NSDate now] forKey:@"birthday"];//时间
      [superProperties setValue:@{@"key":@"value"} forKey:@"object"];//对象
      [superProperties setValue:@[@{@"key":@"value"}] forKey:@"object_arr"];//对象组
      [superProperties setValue:@[@"value"] forKey:@"arr"];//数组
      [instance setSuperProperties:superProperties];//设置公共事件属性
      
      // 开启自动采集事件(安装，启动，关闭事件)
      [[ThinkingAnalyticsSDK sharedInstanceWithAppid:APP_ID]enableAutoTrack:ThinkingAnalyticsEventTypeAppInstall | ThinkingAnalyticsEventTypeAppStart |ThinkingAnalyticsEventTypeAppEnd];
      
      //发送事件
      NSDictionary *eventProperties = @{ @"product_name": @"商品名"};
      [instance track:@"product_buy" properties:eventProperties];
      
      //设置用户属性
      [instance user_set:@{@"username": @"TA"}];
    }
}