menu
Is this helpful?

# iOS

提示

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

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

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

最新版本: v3.0.4

更新时间: 2024-08-01

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

注意

当前文档适用于 v3.0.0 及以后的版本,历史版本请参考 iOS 接入指南(V2) (opens new window)SDK下载(v2.8.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 文件)

# 1.2 手动集成

1.下载并解压 iOS SDK

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

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

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

libz.dylibSecurity.frameworkSystemConfiguration.frameworklibsqlite3.tbd

# 二、 初始化

参数说明:

  • 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, TE 平台将会以账号 ID 作为身份识别 ID,并且设置的账号 ID 将会在调用 logout 之前一直保留。多次调用 login: 将覆盖先前的账号 ID 。

该方法不会上传登录事件

# 3.2 设置公共事件属性

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

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

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

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

# 3.3 开启自动采集

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

// 开启自动采集事件(安装,启动,关闭事件)
[TDAnalytics enableAutoTrack:TDAutoTrackEventTypeAppInstall | TDAutoTrackEventTypeAppStart | TDAutoTrackEventTypeAppEnd];

# 3.4 发送事件

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

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

# 3.5 设置用户属性

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

# 四、最佳实践

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

if (授权隐私政策) {
    // enable log
    [TDAnalytics enableLog:NO];
    
    // SDK needs to be initialized on the main thread
    NSString *appid = @"APPID";
    NSString *url = @"SERVER_URL";
    TDConfig *config = [[TDConfig alloc] init];
    config.appid = appid;
    config.serverUrl = url;
    config.mode = TDModeDebug;
    [TDAnalytics startAnalyticsWithConfig:config];
    
    [TDAnalytics login:@"TD"];
    
    NSDictionary *superProperties = @{
        @"channel": @"ta",
        @"age": @1,
        @"isSuccess": @YES,
        @"birthday": [NSDate date],
        @"object": @{
            @"key":@"value"
        },
        @"object_arr":@[
            @{
                @"key":@"value"
            }
        ],
        @"arr": @[@"value"],
    };
    [TDAnalytics setSuperProperties:superProperties];
    
    [TDAnalytics enableAutoTrack:TDAutoTrackEventTypeAppInstall | TDAutoTrackEventTypeAppStart | TDAutoTrackEventTypeAppEnd];
    
    NSDictionary *eventProperties = @{@"product_name": @"book"};
    [TDAnalytics track:@"product_buy" properties:eventProperties];
    
    // "username" is "ThinkingData"
    [TDAnalytics userSet:@{@"username": @"ThinkingData"}];
}