> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kontext.so/llms.txt
> Use this file to discover all available pages before exploring further.

# 安装

> 把视频 SDK 加入你的 iOS 项目，在启动时初始化，并配置 ATT 和 SKAdNetwork。

> [!NOTE]
>
> 你需要一个[发布方账号](https://docs.kontext.so/zh/publishers.md#启动方式很简单)来获取 `publisherToken`。

## 1. 添加 SDK

在 Xcode 中添加包依赖（File → Add Package Dependencies），或在 `Package.swift` 中：

```swift theme={null}
dependencies: [
    .package(url: "https://github.com/kontextso/sdk-swift-video", .upToNextMajor(from: "0.1.0"))
]
```

然后把 `KontextVideoSDK` 产物加入你的应用 target。

> [!NOTE]
>
> SDK 依赖 [KontextKit](https://github.com/kontextso/kontextkit-ios)，一组共享的 iOS 基础组件（安装 id、设备信息、ATT、同意）。Swift Package Manager 会自动拉取。

## 2. 启动时初始化

在应用启动时尽早调用一次 `initialize(with:)`。它保存配置并在后台联系服务器；没有任何东西等待它。

```swift theme={null}
import KontextVideoSDK

KontextVideo.shared.initialize(with: .init(publisherToken: "<your-publisher-token>"))
```

在 `async` 代码中，同一调用会返回结果状态：

```swift theme={null}
let state = await KontextVideo.shared.initialize(with: .init(publisherToken: "<your-publisher-token>"))
```

第二次调用会被忽略。初始化完成前发出的广告请求只是等待它，所以你可以立即创建 `VideoAds`。

> [!NOTE]
>
> `KontextVideo`、`VideoAds` 和 `VideoAd` 都是 `@MainActor`。请在主 actor 上调用它们，这在 SwiftUI 视图和 `@MainActor` 隔离的视图控制器中是默认的。

### 配置

```swift theme={null}
KontextVideo.Configuration(
    publisherToken: "<your-publisher-token>",
    requestTrackingAuthorization: true,    // SDK 在第一次广告请求前请求 ATT；默认 false
    logLevel: .warning                      // .none、.error、.warning、.info、.debug
)
```

集成期间使用 `logLevel: .debug`；它会把每次请求、每个广告和每个事件记录到控制台，子系统为 `so.kontext.video`。

## 3. 设置 IDFA（App Tracking Transparency）

在 `Info.plist` 中加入 `NSUserTrackingUsageDescription`：

```xml theme={null}
<key>NSUserTrackingUsageDescription</key>
<string>我们使用你的广告标识符来展示更相关的广告。</string>
```

视频 SDK 默认不展示 ATT 对话框：视频应用通常有自己合适的时机。你可以自己请求，或设置 `requestTrackingAuthorization: true`，SDK 会在第一次广告请求前询问。无论哪种方式，观众允许后 SDK 都会读取 IDFA。

`Info.plist` 键、提示时机的注意事项，以及如何自行管理提示，见 [IFA 与 ATT](https://docs.kontext.so/zh/video/guides/ifa.md)。

## 4. 设置 SKAdNetwork

把 Kontext 的广告网络标识符，以及我们在入驻时提供的 DSP 标识符，加入 `Info.plist`：

```xml theme={null}
<key>SKAdNetworkItems</key>
<array>
  <dict>
    <key>SKAdNetworkIdentifier</key>
    <string>mp7rpxwdrx.adattributionkit</string>
  </dict>
</array>
```

没有 Kontext 的标识符，直投广告活动带来的安装将无法归因，且没有任何提示。完整指南见 [SKAdNetwork](https://docs.kontext.so/zh/video/guides/skadnetwork.md)。

## 5. 同意

如果你的应用运行符合 TCF 的同意平台，SDK 每次请求都读取它写入 `UserDefaults` 的 IAB 同意键；无需任何操作。COPPA 无法从设备读取，请自行设置：

```swift theme={null}
KontextVideo.shared.regulatory = .init(coppa: false)
```

见 [TCF 与 CMP](https://docs.kontext.so/zh/video/guides/tcf-cmp.md)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.