index.mdoc

---
title: iOS SDK 集成指南
description: 使用 iOS SDK 在您的 iOS 应用中使用 Adjust 功能
category-title: iOS SDK
slug: zh/sdk/ios
sidebar-position: 2
versions:
  - label: v5
    value: v5
    default: true
  - label: v4
    value: v4
redirects:
  v4: /zh/sdk/ios/v4
---

通过 Adjust iOS SDK，您可以在 iOS 应用中记录归因、事件以及更多信息。该指南展示了如何将 Adjust SDK 集成至应用。

{% callout type="important" %}
Adjust SDK 支持 iOS 12 或更新版本。{% callout /%}

1. 添加 SDK 至您的项目{% #add-the-sdk-to-your-project %}

---

要在您的 iOS 应用中使用 Adjust SDK，请先将 SDK 加入 Xcode 项目。

要使用 Swift package manager 添加 SDK：

1. 选择 **File --> Swift Packages --> Add Package Dependency**
1. 在出现的文本框中输入 SDK 的 GitHub 地址： `https://github.com/adjust/ios_sdk`
1. 在 **Version** 下拉菜单中选择要使用的 Adjust SDK 版本。请查看[发布页面](https://github.com/adjust/ios_sdk/releases)，找到最新版本。

### 其他安装方法{% #alternative-installation-methods %}

{% tabs %}
{% tab title="Cocoapods" sync="cocoapods" %}
要使用 Cocoapods 添加 SDK，请在 `Podfile` 中指定要使用的版本：

```rb
# Get pod from repository
pod 'Adjust', '~> {% $versions.ios.v5 %}'
```

如果您在应用中使用的是 web 视图，请添加下列行以加入 Adjust Web Bridge：

```rb
pod 'Adjust/AdjustWebBridge', '~> {% $versions.ios.v5 %}'
```
{% /tab %}

{% tab title="Carthage" sync="carthage" %}
要使用 Carthage 添加 SDK，请将下列内容添加至您的 `Cartfile`：

```text
github "adjust/ios_sdk"
```
{% /tab %}
{% /tabs %}

2. 集成 Adjust SDK{% #integrate-the-adjust-sdk %}

---

将 Adjust SDK 添加到 `Xcode` 项目后，您需要将其集成至应用。

在您的项目文件中添加相关导入语句：

{% tabs %}
{% tab title="Swift" sync="swift" %}
要导入 Adjust SDK，请将下列行添加至您的桥接标头文件：

```swift
import AdjustSdk
```
{% /tab %}

{% tab title="Objective-C" sync="objc" %}
要导入 Adjust SDK，请将下列行添加至您的`AppDelegate.h`文件：

```objc
#import <AdjustSdk/AdjustSdk.h>
```
{% /tab %}
{% /tabs %}

3. 添加 iOS 框架{% #add-ios-frameworks %}

---

Adjust SDK 依赖各种框架读取具体设备信息。要启用设备信息读取，请添加对应框架，并将其标记为 **可选** 。

| 框架                                  | 描述                                                                 | 注意事项                                                         |
| ----------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------ |
| `AdSupport.framework`               | 允许读取设备 IDFA。对于操作系统为 iOS 14 及更早版本的设备，添加该框架也会允许读取 LAT 信息。            | 如果您的应用属于 "儿童" 类别，那么请勿添加该框架。                                  |
| `AdServices.framework`              | 处理 ASA 归因。                                                         |                                                              |
| `StoreKit.framework`                | 允许访问 SKAdNetwork 框架。                                               | 若要允许 Adjust 处理 iOS 14 或更新操作版本设备上与 SKAdNetwork 的通讯，那么必须添加该框架。 |
| `AppTrackingTransparency.framework` | 若要允许 Adjust SDK 包装用户 ATT 许可对话，并读取 iOS 14 或更新操作版本设备的许可响应，那么必须添加该框架。 | 如果您的应用属于 "儿童" 类别，那么请勿添加该框架                                   |
| `WebKit.framework`                  | 允许在您的应用中使用 web 视图。                                                 | 只有在应用使用 web 视图时才有必要                                          |

4. 设置 SDK 签名{% #set-up-sdk-signature %}

---

如果您想使用 SDK 签名库来保护 Adjust SDK 与 Adjust 服务器之间的通信，请按照[Adjust 帮助中心 SDK 签名指南中的说明](https://help.adjust.com/zh/article/sdk-signature)进行操作。

5. (可选) 设置 Adjust Web Bridge{% #set-up-web-bridge %}

---

如果您的应用使用的是 web 视图，请务必设置 Adjust Web Bridge，以记录 web 视图中的信息。

### 将 `AdjustBridge` 集成到您的应用中{% #integrate-adjustbridge-into-your-app %}

在项目导航中：

1. 打开您的视图控制器 (View Controller) 源文件。
1. 在文件顶端添加 `import` 导入语句。
1. 在 Web View Delegate 的 `viewDidLoad` 或 `viewWillAppear` 方法中，添加下列 `AdjustBridge` 调用：

{% tabs %}
{% tab title="Swift" sync="swift" %}
```swift
import AdjustSdk

func viewWillAppear(_ animated: Bool) {
    let webView = WKWebView(frame: view.bounds)

    // add var adjustBridge: AdjustBridge? on your interface
    adjustBridge.loadWKWebViewBridge(webView)
}
```
{% /tab %}

{% tab title="Objective-C" sync="objc" %}
```objc
#import <AdjustSdk/AdjustSdk.h>

- (void)viewWillAppear:(BOOL)animated {
    WKWebView *webView = [[WKWebView alloc] initWithFrame:self.view.bounds];

    // add @property (nonatomic, strong) AdjustBridge *adjustBridge; on your interface
    [self.adjustBridge loadWKWebViewBridge:webView];
}

// Your code here
```
{% /tab %}
{% /tabs %}

#### 将 `AdjustBridge` 集成进您的 web 视图{% #integrate-adjustbridge-into-your-web-view %}

要在 web 视图上使用 Javascript bridge，您就需要配置 bridge。请添加下列 Javascript 代码，初始化 Adjust iOS web bridge：

{% tabs %}
{% tab title="Javascript" sync="js" %}
```js
var yourAppToken = yourAppToken;
var environment = AdjustConfig.EnvironmentSandbox;
var adjustConfig = new AdjustConfig(yourAppToken, environment);
Adjust.initSdk(adjustConfig);
```
{% /tab %}
{% /tabs %}

6. 初始化 Adjust SDK{% #initialize-the-adjust-sdk %}

---

要初始化 Adjust SDK，您需要创建一个 config 对象。该对象包含控制 Adjust SDK 行为的配置选项。发送以下参数能够保证最少的设置：

* `appToken`: 您的应用识别码。
* `environment`: SDK 运行的环境。将其设为`ADJEnvironmentSandbox` 。

要使用此 config 对象初始化 Adjust SDK：

1. 在您应用委托的 `didFinishLaunching` 或 `didFinishLaunchingWithOptions` 方法中声明 config 对象。
1. 将 config 对象的 `logLevel` 属性设置为 `ADJLogLevelVerbose` (详细)。您必须启用 verbose 日志记录，才能调取设备信息。
1. 将 config 对象作为参数发送至`initSdk`方法。

{% tabs %}
{% tab title="Swift" sync="swift" %}
```swift
import AdjustSdk

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        // Override point for customization after application launch.
        let yourAppToken = "{YourAppToken}"
        let environment = ADJEnvironmentSandbox
        let adjustConfig = ADJConfig(appToken: yourAppToken,
                                     environment: environment)

        Adjust.initSdk(adjustConfig)
       //...
        return true
 }
```
{% /tab %}

{% tab title="Objective-C" sync="objc" %}
```objc
#import <AdjustSdk/AdjustSdk.h>

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
   NSString *yourAppToken = @"{YourAppToken}";
   NSString *environment = ADJEnvironmentSandbox;
   ADJConfig *adjustConfig = [[ADJConfig alloc] initWithAppToken:appToken
                                                environment:environment];
   // Your code here
   [Adjust initSdk:myAdjustConfig];
   // Your code here
   return YES;
}
```
{% /tab %}

{% tab title="Javascript" sync="js" %}
```js
var yourAppToken = yourAppToken;
var environment = AdjustConfig.EnvironmentSandbox;
var adjustConfig = new AdjustConfig(yourAppToken, environment);
Adjust.initSdk(adjustConfig);
```
{% /tab %}
{% /tabs %}

### 设置您的 iMessage 应用{% #set-up-your-imessage-app %}

{% callout type="important" %}
iMessage 拓展拥有不同的 Bundle ID，并在不同的内容空间中运行。如果您在两者的配置中使用了同样的识别码，那么 SDK 就会返回混合数据。请务必在 Adjust 控制面板中为 iMessage 应用创建单独的应用，然后使用单独的识别码初始化 Adjust SDK。{% callout /%}

如果您的应用面向 iMessage，那么您还需要进行下列额外的配置：

* 如果您是从源代码添加 Adjust SDK，请确保您已在 iMessage 项目中添加了预处理宏 `ADJUST_IM=1`。
* 如果您将 SDK 作为框架添加，请务必在 **Build Phases** 项目设置中添加 **New Copy Files Phase** 。将 `AdjustSdkIm.framework` 复制到 Frameworks 文件夹。

#### 记录会话{% #record-sessions %}

Adjust SDK 并未订阅 iMessage 应用中的 iOS 系统通知。要在应用进入或离开前台时通知 Adjust SDK，请调用 `trackSubsessionStart` 和 `trackSubsessionEnd` 方法。

在 `didBecomeActiveWithConversation:` 方法中添加对 `trackSubsessionStart` 的调用：

{% tabs %}
{% tab title="Swift" sync="swift" %}
```swift
func didBecomeActive(with conversation: MSConversation) {
    // Called when the extension is about to move from the inactive to active state.
    // This will happen when the extension is about to present UI.
    // Use this method to configure the extension and restore previously stored state.

    Adjust.trackSubsessionStart()
}
```
{% /tab %}

{% tab title="Objective-C" sync="objc" %}
```objc
-(void)didBecomeActiveWithConversation:(MSConversation *)conversation {
    // Called when the extension is about to move from the inactive to active state.
    // This will happen when the extension is about to present UI.
    // Use this method to configure the extension and restore previously stored state.

    [Adjust trackSubsessionStart];
}
```
{% /tab %}
{% /tabs %}

在 `willResignActiveWithConversation:` 方法中添加对 `trackSubsessionEnd` 的调用：

{% tabs %}
{% tab title="Swift" sync="swift" %}
```swift
func willResignActive(with conversation: MSConversation) {
    // Called when the extension is about to move from the active to inactive state.
    // This will happen when the user dismisses the extension, changes to a different
    // conversation or quits Messages.

    // Use this method to release shared resources, save user data, invalidate timers,
    // and store enough state information to restore your extension to its current state
    // in case it is terminated later.

    Adjust.trackSubsessionEnd()
}
```
{% /tab %}

{% tab title="Objective-C" sync="objc" %}
```objc
-(void)willResignActiveWithConversation:(MSConversation *)conversation {
    // Called when the extension is about to move from the active to inactive state.
    // This will happen when the user dismisses the extension, changes to a different
    // conversation or quits Messages.

    // Use this method to release shared resources, save user data, invalidate timers,
    // and store enough state information to restore your extension to its current state
    // in case it is terminated later.

    [Adjust trackSubsessionEnd];
}
```
{% /tab %}
{% /tabs %}

7. 配置 Adjust SDK{% #configure-the-adjust-sdk %}

---

添加 config 对象和初始化逻辑后，您可以配置 Adjust SDK 来记录应用不同部分的信息。请查看[配置参考](/zh/sdk/ios/configuration)和[功能指南](/zh/sdk/ios/features)准确设置您想记录的内容。

8. 测试 Adjust SDK{% #test-the-adjust-sdk %}

---

完成配置，能通过 Adjust SDK 记录应用相关信息后，您就可以进行测试了。Adjust 为您提供[测试控制台](https://help.adjust.com/zh/article/testing-console)和[设备 ID](https://help.adjust.com/zh/article/device-api)，方便您测试应用。

请按照[测试指南](https://help.adjust.com/zh/article/test-the-adjust-sdk)中的说明操作，确保您的应用能将预期值发送给 Adjust。

9. 针对生产环境构建应用{% #build-your-app-for-production %}

---

完成测试后，您就可以针对生产环境构建应用了。为此，请更新您的 config 对象。

更新以下值：

* `environment`: 将其设为`ADJEnvironmentProduction` 。
* `logLevel`: 选择[日志级别](/zh/sdk/ios/configuration#set-your-logging-level)，或在 config 对象中传送 `allowSuppressLogLevel` 参数，以完全禁用日志记录。

{% tabs %}
{% tab title="Swift" sync="swift" %}
```swift
import AdjustSdk

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        // Override point for customization after application launch.
        let yourAppToken = "{YourAppToken}"
        let environment = ADJEnvironmentProduction
        let adjustConfig = ADJConfig(
            appToken: yourAppToken,
            environment: environment,
            suppressLogLevel: true)
        adjustConfig?.logLevel = ADJLogLevel.verbose
        //...
        Adjust.initSdk(adjustConfig)
       //...
        return true
}
```
{% /tab %}

{% tab title="Objective-C" sync="objc" %}
```objc
#import <AdjustSdk/AdjustSdk.h>

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
   NSString *yourAppToken = @"{YourAppToken}";
   NSString *environment = ADJEnvironmentSandbox;
   ADJConfig *adjustConfig = [[ADJConfig alloc] initWithAppToken:appToken
                                                environment:environment
                                                suppressLogLevel:YES];
   [adjustConfig setLogLevel:ADJLogLevelVerbose];
   //...
   [Adjust initSdk:adjustConfig];
   //...
   return YES;
}
```
{% /tab %}
{% /tabs %}

您可以使用 `Xcode` 版本标记 (flag)，根据您创建的版本 (调试或生产版本) 情况动态更新 config。

{% tabs %}
{% tab title="Swift" sync="swift" %}
```swift
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        // Override point for customization after application launch.
        let yourAppToken = "{YourAppToken}"

        #if DEBUG
        let environment = ADJEnvironmentSandbox
        let adjustConfig = ADJConfig(
            appToken: yourAppToken,
            environment: environment)
        adjustConfig?.logLevel = ADJLogLevel.verbose

        #else
        let environment = ADJEnvironmentProduction
        let adjustConfig = ADJConfig(
            appToken: yourAppToken,
            environment: environment)
        adjustConfig?.logLevel = ADJLogLevel.suppress
        #endif
        //...
        Adjust.initSdk(adjustConfig)
        //...
        return true
}
```
{% /tab %}

{% tab title="Objective-C" sync="objc" %}
```objc
#import <AdjustSdk/AdjustSdk.h>

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
   NSString *yourAppToken = @"{YourAppToken}";

   #if DEBUG
   NSString *environment = ADJEnvironmentSandbox;
   ADJConfig *adjustConfig = [[ADJConfig alloc] initWithAppToken:appToken
                                                environment:environment];
   [adjustConfig setLogLevel:ADJLogLevelVerbose];

   #else
   NSString *environment = ADJEnvironmentProduction;
   ADJConfig *adjustConfig = [[ADJConfig alloc] initWithAppToken:appToken
                                                environment:environment];
   [adjustConfig setLogLevel:ADJLogLevelSuppress];
   #endif
   //...
   [Adjust initSdk:adjustConfig];
   //...
   return YES;
}
```
{% /tab %}
{% /tabs %}
{% /callout %}
{% /callout %}