# iOS SDK 集成

> 使用 CocoaPods 或手动方法将 LevelPlay SDK 集成到 iOS app 中，并使用 app 密钥对其进行初始化。

LevelPlay SDK 支持 CocoaPods、Swift Package Manager 和手动下载机制来集成 SDK。

## 先决条件##prerequisites

iOS 版本支持是按网络定义的。LevelPlay 广告服务和 LevelPlay 聚合支持 iOS 版本 12+ 和 Xcode 版本 15.4+。

为了与 iOS 14 兼容，LevelPlay 发布了 SDK 7+，支持 SKAdNetwork 归因。

## 将 SDK 添加到您的项目中##add-the-sdk-to-your-project

### CocoaPods##cocoapods

[CocoaPods](https://cocoapods.org/) 是 Objective-C 和 Swift 的依赖项管理器；它可以自动执行并简化 SDK 集成过程。有关更多信息，请参阅关于[入门](https://guides.cocoapods.org/using/getting-started.html)和[使用 CocoaPods](https://guides.cocoapods.org/using/using-cocoapods.html) 的 CocoaPods 文档。

要将 LevelPlay SDK 与 CocoaPods 集成，请在 Pod 文件中输入以下行：

```objective-c
pod 'IronSourceSDK','9.5.0.0'
```

如果在项目中不使用 Swift，请选择**项目** > **构建设置** > **链接** > **运行路径搜索路径**，然后添加以下代码：

```objective-c
// needs to be first on the list 
/usr/lib/swift
```

> **Note:**
>
> 从版本 8.9.0 开始，Ad 品质 集成到 LevelPlay SDK 中，并在实现 LevelPlay 时自动初始化。有关更多信息，请参阅[广告品质概述](/grow/ad-quality/overview.md)。

### Swift Package Manager##swift-package-manager

> **Note:**
>
> 要使用 Swift Package Manager，必须具有支持的最低 LevelPlay SDK 9.3.0 版本以及在[Minimum adapter and network SDK versions 部分](#minimum-adapter)中定义的相应适配器版本。

要将软件包依赖项项添加到项目中，请完成以下步骤：

1. 在 Xcode 中，转到**文件** > **添加软件包依赖项**。
2. 在显示的提示词中，搜索以下软件包网址：
   `https://github.com/ironsource-mobile/LevelPlay-Swift-Package`
3. 在依赖项规则中，选择 **Branch**。
4. 在文本字段中，输入 `main`。

#### 添加聚合网络适配器包##add-mediation-network-adapter-packages

每个聚合网络都有自己的适配器 Swift 软件包，托管在 [IronSource 移动端 GitHub 组织](https://github.com/orgs/ironsource-mobile/repositories?q=Swift-Package)中。适配器代码仓库使用命名格式`LevelPlay-<Network>-Adapter-Swift-Package`。例如，Unity Ads 适配器位于`LevelPlay-UnityAds-Adapter-Swift-Package`代码仓库中，而 AdMob 适配器位于`LevelPlay-AdMob-Adapter-Swift-Package`代码仓库中。

要将聚合网络适配器软件包添加到项目中，请完成以下步骤：

1. 在 [IronSource 移动端 GitHub 组织](https://github.com/orgs/ironsource-mobile/repositories?q=Swift-Package)中，找到要添加的网络的适配器代码仓库。
2. 复制代码仓库网址。
3. 在 Xcode 中，转到**文件** > **添加软件包依赖项**。
4. 在显示的提示词中，输入适配器代码仓库网址。
5. 在依赖项规则中，选择 **Exact Version**。
6. 输入与项目 LevelPlay SDK 版本兼容的已标记适配器版本。

要选择兼容的版本，请参阅[最低适配器和网络 SDK 版本](#minimum-adapter)部分和相关适配器更改日志。对要添加的每个聚合网络重复这些步骤。

#### 最小适配器和网络 SDK 版本##minimum-adapter

| 网络名称            | 最小适配器版本 | 最低网络 SDK 版本 |
| --------------- | ------- | ----------- |
| Unity Ads       | 5.8.1   | 4.16.5      |
| AppLovin        | 5.7.1   | 13.6.2      |
| BidMachine      | 5.7.1   | 3.6.1       |
| Digital Turbine | 5.8.1   | 8.4.6       |
| Google AdMob    | 5.10.1  | 13.2.0      |
| HyprMX          | 5.3.1   | 6.4.6       |
| LY Ad Network   | 5.4.1   | 3.0.1       |
| Meta            | 5.3.1   | 6.21.1      |
| Mintegral       | 5.18.1  | 8.1.0       |
| MobileFuse      | 5.2.0   | 1.11.0      |
| MyTarget        | 5.11.1  | 5.41.0      |
| Ogury           | 5.5.1   | 5.2.1       |
| Pangle          | 5.28.1  | 7.9.1.1     |
| 巫毒              | 5.2.1   | 3.15.1      |
| Vungle          | 5.10.1  | 7.7.4       |
| Yandex          | 5.9.1   | 8.1.0       |

### 手动下载##manual-download

要手动将 LevelPlay SDK 添加到项目中，请完成以下步骤：

1. [下载 iOS SDK 9.5.0 版。](https://github.com/ironsource-mobile/iOS-sdk/raw/master/9.5.0/IronSource9.5.0.zip)
2. 解压缩 SDK 并向 Xcode 项目添加`IronSource.framework`。
3. 将以下链接器标志添加到构建设置：**目标** > **构建设置** > **链接** > **其他链接器标志**：
4. 导入库 - "z","sqlite3.0"
5. 导入框架 - “JavaScriptCore”、“WebKit”、“AdSupport”、“SystemConfiguration”

### LevelPlay 聚合演示应用程序##levelplay-mediation-demo-app

Integration demo 应用程序演示了如何在 app 中集成 LevelPlay Mediation。

[下载 iOS demo 应用程序](https://github.com/ironsource-mobile/Mediation-Demo-Apps)

## 更新属性列表文件##update-the-property-list-file

### SKAdNetwork 支持##skadnetwork-support

要在使用 SDK 7+ 启用 Ironsource 网络广告服务的显示，请确保在app属性列表文件 (Info.plist) 中包含 Ironsource ad network ID。 

1. 在 Xcode 项目导航器中，选择 **Info.plist**。
2. 选择属性列表编辑器中某个键旁边的 **Add** (+)，然后选择 **Return**。
3. 输入键名称 **SKAdNetworkItems**。
4. 在 **Type** 列中，选择 **Array**。
5. 创建字典项，然后创建单个字字符串项。
6. 输入键名称 **SKAdNetworkIdentifier** 和以下键值：

   ```text
   su67r6k2v3.skadnetwork
   ```

还可以使用以下代码将 **SKAdNetworkIdentifier** 添加到 Info.plist 文件： 

```xml
<key>SKAdNetworkItems</key>
<array>
   <dict>
      <key>SKAdNetworkIdentifier</key>
      <string>su67r6k2v3.skadnetwork</string>
   </dict>
</array>
```

如需了解编辑属性列表的更多信息，请参阅 [Xcode 文档](https://help.apple.com/xcode/mac/current/#/dev3f399a2a6)。

### 通用 SKAN 报告##universal-skan-reporting

要接收广告应用的所有需求来源的获胜安装验证回传副本，请在应用的 Info.plist 文件中添加 [NSAdvertisingAttributionReportEndpoint](https://developer.apple.com/documentation/bundleresources/information_property_list/nsadvertisingattributionreportendpoint) 密钥。

1. 在 Xcode 项目导航器中，选择 **Info.plist**。
2. 选择属性列表编辑器中某个键旁边的 **Add** (+)，然后选择 **Return**。
3. 输入键名称 [NSAdvertisingAttributionReportEndpoint](https://developer.apple.com/documentation/bundleresources/information_property_list/nsadvertisingattributionreportendpoint)。
4. 在 **Type** 列中，选择 **String**。
5. 输入以下网址：`https://postbacks-is.com/`。

有关通用 SKAN 报告的更多信息，请参阅[手动添加 SKAdNetwork ID](/grow/levelplay/sdk/ios/skadnetwork-id-manager.md)。

### app 传输安全设置##app-transport-security-settings

为确保在所有聚合网络中不间断地支持 LevelPlay 广告投放，请在 Info.plist 文件中进行以下更改：

* 通过选择加号符号添加字典`NSAppTransportSecurity`。确保将此字典添加到 Top Level Key。
  * 在此字典中，添加一个名为 `NSAllowsArbitraryLoads` 的布尔值，并通过选择选项卡将其设置为 `YES`。
* 确保 Info.plist 文件不包含除 `NSAllowsArbitraryLoads` 之外的任何其他异常，因为这可能会产生冲突。
* 有关 app 传输安全性的更多信息，请参阅 [Apple 文档](https://developer.apple.com/library/prerelease/ios/documentation/General/Reference/InfoPlistKeyReference/Articles/CocoaKeys.html#//apple_ref/doc/uid/TP40009251-SW33)。

## 初始化 LevelPlay SDK##initialize-the-levelplay-sdk

### 导入必要的文件##import-the-necessary-files

```objective-c
#import "IronSource/IronSource.h"
```

### 初始化 SDK##init-the-sdk

要初始化 LevelPlay SDK，请完成以下步骤：

1. 定义完成处理程序的成功和失败。
2. 使用 appKey 和用户 ID（如果相关）调用 LevelPlay init API。

如果使用服务器到服务器回调（奖励用户）或使用广告品质用户旅程，请将用户 ID 添加为初始化请求构建器的一部分。

1. **Objective-C**

   ```objective-c
       // 创建具有 app 密钥和广告格式的请求构建器。添加 User ID（如果有）
   LPMInitRequestBuilder *requestBuilder = [[LPMInitRequestBuilder alloc] initWithAppKey:@"appKey"];
   [requestBuilder withUserId:@"UserId"];

   // Build the initial request
   LPMInitRequest *initRequest = [requestBuilder 构建];
   // Initialize LevelPlay with the prepared request
   [LevelPlay initWithRequest:initRequest 完成：^(LPMConfiguration *_Nullable 配置，NSError *_Nullable 报错){

      if(error) {
          // There was an error on initialization.采取必要的操作或重试
      } else {
         // Initialization was successful.您现在可以创建广告对象并加载广告服务或执行其他任务         
      }
   }];
   ```

2. **Swift**

   ```swift
   // 创建具有 app 密钥和广告格式的请求构建器。添加 User ID（如果有）
   let requestBuilder = LPMInitRequestBuilder(appKey："appKey")
      .withUserId("UserId")
   // 构建初始请求
   let initRequest = requestBuilder.build()
   // 使用准备好的请求初始化 LevelPlay 
   LevelPlay.initWith(initRequest) 
   { config，报错
   if let error = error {
      // 初始化时报错。采取必要的操作或重试
   } else {
      // 初始化成功。您现在可以创建广告对象并加载广告服务或执行其他任务
   }
   }
   ```

### 初始化结果##initialization-result

* **成功**：初始化成功完成时触发。收到此指示后，您可以创建和加载广告。
* **报错**：未成功检索配置，无法加载广告服务。建议的最佳做法是稍后在互联网连接可用或故障原因得到解决时尝试并初始化 LevelPlay SDK。

## 验证您的集成##verify-your-integration

使用 [LevelPlay 集成测试套件](/grow/levelplay/sdk/ios/integration-test-suite.md)可测试 app 的集成情况、验证平台设置并审查与配置的网络相关的广告服务。 

要在 app 中启用测试套件，请在设置 init 之前调用 setMetaData API：

1. **Objective-C**

   ```objective-c
   [LevelPlay setMetaDataWithKey:@"is_test_suite" value:@"enable"];
   ```

2. **Swift**

   ```swift
   LevelPlay.setMetaDataWithKey("is_test_suite", value: "enable")
   ```

聚合初始化完成后，通过调用以下方法启动测试套件：

1. **Objective-C**

   ```objective-c
   [LevelPlay launchTestSuite:self];
   ```

2. **Swift**

   ```swift
   LevelPlay.launchTestSuite(self)
   ```

## 后续步骤##next-steps

1. 请参阅以下集成指南以实现广告格式：
   * [奖励视频](/grow/levelplay/sdk/ios/rewarded-ads-integration.md)
   * [插页式视频](/grow/levelplay/sdk/ios/interstitial-integration.md)
   * [横幅广告](/grow/levelplay/sdk/ios/banner-integration.md)
   * [原生广告服务](/grow/levelplay/sdk/ios/native-ads-integration.md)
2. 在 app 中集成奖励视频、插页式或横幅广告服务。请参阅 [iOS 调解网络](/grow/levelplay/sdk/ios/mediation-networks.md)。