---
code: ios_sdk_installation
name: "iOS"
wikiToken: RCJRwHveBi4YRBk2AqncI0VqncS
parentWikiToken: FTcTwinIOi3OiRkK4MPc2Ex7neg
updateTime: 1773312570000
sourceUrl: https://docs-v2.thinkingdata.cn/?version=v5.0&lan=zh-CN&code=ios_sdk_installation
---
# iOS

::: tip 提示

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

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

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

:::

**最新版本: **v3.3.5

**更新时间:** 2026-03-12

**资源下载: **源代码 下载

::: warning 注意

当前文档适用于 v3.0.0 及以后的版本，历史版本请参考 iOS 接入指南（V2），SDK下载（v2.8.4）

::: 

### 一、集成 SDK

#### 1.1 自动集成

- 使用 CocoaPods 安装 SDK
1.创建并编辑 Podfile 内容（如果已有，直接编辑）：

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

```
pod init
```

编辑 Podfile 的内容如下：

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

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

```
pod install
```

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

3.导入成功，启动工程

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

#### 1.2 手动集成 

1.下载并解压 iOS SDK

2.将`ThinkingSDK.xcframework`、`ThinkingDataCore.xcframework`拖入 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`

### 二、 初始化 

:::: el-tabs

::: el-tab-pane label=Objective-C

```
#import <ThinkingSDK/ThinkingSDK.h>

NSString *appid = @"APPID";
NSString *url = @"SERVER_URL";
    
//第一种
[TDAnalytics startAnalyticsWithAppId:appid serverUrl:url];
    
//第二种
TDConfig *config = [[TDConfig alloc] init];
config.appid = appid;
config.serverUrl = url;
[TDAnalytics startAnalyticsWithConfig:config];
```

:::

::: el-tab-pane label=Swift

```
// SDK needs to be initialized on the main thread

**let** appid = "APPID";
**let** url = "SERVER_URL";

//第一种
TDAnalytics.start(withAppId: appid, serverUrl: url)

//第二种
**let** config = TDConfig(appId: appid, serverUrl: url)
TDAnalytics.start(with: config)
```

:::

::::

参数说明:

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

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

#### 3.1 设置账号ID

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

:::: el-tabs

::: el-tab-pane label=Objective-C

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

:::

::: el-tab-pane label=Swift

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

:::

::::

<!-- unsupported block: 34 -->

**该方法不会上传登录事件**

#### 3.2 设置公共事件属性

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

:::: el-tabs

::: el-tab-pane label=Objective-C

```
NSDictionary *superProperties = @{
    @"channel": @"ta",
    @"age": @1,
    @"isSuccess": @YES,
    @"birthday": [NSDate date],
    @"object": @{
        @"key":@"value"
    },
    @"object_arr":@[
        @{
            @"key":@"value"
        }
    ],
    @"arr": @[@"value"],
};
[TDAnalytics setSuperProperties:superProperties];
```

:::

::: el-tab-pane label=Swift

```
var superProperties: [String : 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"]

TDAnalytics.setSuperProperties(superProperties)
```

:::

::::

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

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

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

#### 3.3 开启自动采集

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

:::: el-tabs

::: el-tab-pane label=Objective-C

```
[TDAnalytics enableAutoTrack:TDAutoTrackEventTypeAppInstall | TDAutoTrackEventTypeAppStart | TDAutoTrackEventTypeAppEnd];
```

:::

::: el-tab-pane label=Swift

```
TDAnalytics.enableAutoTrack([.appStart, .appEnd, .appInstall])
```

:::

::::

#### 3.4 发送事件

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

:::: el-tabs

::: el-tab-pane label=Objective-C

```
NSDictionary *eventProperties = @{@"product_name": @"book"};
[TDAnalytics track:@"product_buy" properties:eventProperties];
```

:::

::: el-tab-pane label=Swift

```
let properties = ["product_name": "book"] as [String: Any]
TDAnalytics.track("product_buy", properties: properties)
```

:::

::::

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

#### 3.5 设置用户属性

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

:::: el-tabs

::: el-tab-pane label=Objective-C

```
//此时"username"为"ThinkingData"
[TDAnalytics userSet:@{@"username": @"ThinkingData"}];
//此时"username"为"TA"
[TDAnalytics userSet:@{@"username": @"TA"}];
```

:::

::: el-tab-pane label=Swift

```
//此时"username"为"ThinkingData"
TDAnalytics.userSet(["usernaame": "ThinkingData"])
//此时"username"为"TA"
TDAnalytics.userSet(["usernaame": "TA"])
```

:::

::::

### 四、最佳实践

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

:::: el-tabs

::: el-tab-pane label=Objective-C

```
if (授权隐私政策) {
    //开启日志
    [TDAnalytics enableLog:NO];
    
    //SDK初始化
    NSString *appid = @"APPID";
    NSString *url = @"SERVER_URL";
    TDConfig *config = [[TDConfig alloc] init];
    config.appid = appid;
    config.serverUrl = url;
    [TDAnalytics startAnalyticsWithConfig:config];
    
    //开启自动采集
    [TDAnalytics enableAutoTrack:TDAutoTrackEventTypeAppInstall | TDAutoTrackEventTypeAppStart | TDAutoTrackEventTypeAppEnd];
    
    [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];
        
    NSDictionary *eventProperties = @{@"product_name": @"book"};
    [TDAnalytics track:@"product_buy" properties:eventProperties];
    
    [TDAnalytics userSet:@{@"username": @"ThinkingData"}];
}

```

:::

::: el-tab-pane label=Swift

```
if (授权隐私政策) {
    //开启日志
    TDAnalytics.enableLog(true)
    
    //SDK初始化
    let appid = "app_id";
    let url = "server_url";
    let config = TDConfig(appId: appid, serverUrl: url)
    TDAnalytics.start(with: config)
    
    //开启自动采集
    TDAnalytics.enableAutoTrack([.appStart, .appEnd, .appInstall])
    
    TDAnalytics.login("TD")
    
    var superProperties: [String : 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"]
    TDAnalytics.setSuperProperties(superProperties)
    
    let eventProperties : [String: Any] = ["product_name": "book"]
    TDAnalytics.track("test", properties: eventProperties)
    
    TDAnalytics.userSet(["level": "1"])
 }
```

:::

::::
