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

# iOS SDK 接入

> 快速集成 iOS RUM SDK，实时监控应用性能、错误和用户行为

<Info>
  Flashduty iOS RUM SDK 支持 **iOS 12.0、iPadOS 12.0、tvOS 12.0** 及以上版本。通过集成 SDK，您可以实时监控 iOS 应用的性能、错误和用户行为。
</Info>

<Note>
  **关于依赖和包名的说明**

  Flashduty iOS SDK 完全兼容 Datadog 开源协议。在 Swift Package Manager 或 CocoaPods 中添加依赖时使用 `FlashcatCore`、`FlashcatRUM` 等名称，但在代码中 import 时使用 `DatadogCore`、`DatadogRUM` 等模块名。您可以无缝复用 Datadog 生态的文档、示例和最佳实践，同时享受 Flashduty 平台的服务。
</Note>

## 接入步骤

<Steps>
  <Step title="添加 SDK 依赖">
    Flashduty iOS SDK 支持 Swift Package Manager 和 CocoaPods 两种安装方式：

    <Tabs>
      <Tab title="Swift Package Manager">
        1. 在 Xcode 中，打开您的项目，选择 **File > Add Package Dependencies**

        2. 在搜索栏中输入 Flashduty SDK 的 Git 仓库 URL：
           ```
           https://github.com/flashcatcloud/fc-sdk-ios
           ```

        3. 选择版本规则：
           * **推荐**：选择 **Up to Next Major Version**，并输入当前最新版本号（如 `0.3.0`）
           * 这样可以在保持兼容性的同时获取 bug 修复和小版本更新

        4. 点击 **Add Package**，等待 Xcode 下载依赖

        5. 在弹出的 **Choose Package Products** 窗口中，选择需要添加到 Target 的模块：
           * `FlashcatCore` - 核心 SDK（必选）
           * `FlashcatRUM` - RUM 功能模块（必选）
           * `FlashcatWebViewTracking` - WebView 追踪（可选）
           * `FlashcatCrashReporting` - 崩溃报告（推荐）

        6. 确保每个模块都关联到正确的 Target，点击 **Add Package** 完成添加
      </Tab>

      <Tab title="CocoaPods">
        在项目的 `Podfile` 中添加以下依赖：

        ```ruby Podfile theme={null}
        pod 'FlashcatCore', '~> 0.3.0'    # 核心 SDK（必选）
        pod 'FlashcatRUM', '~> 0.3.0'     # RUM 功能（必选）

        # 可选模块
        pod 'FlashcatWebViewTracking', '~> 0.3.0'   # WebView 追踪
        pod 'FlashcatCrashReporting', '~> 0.3.0'    # 崩溃报告
        ```

        然后执行 `pod install`，并使用 `.xcworkspace` 文件打开项目。
      </Tab>
    </Tabs>

    <Tip>
      **获取最新版本号**

      查看 [SDK 版本发布页面](https://github.com/flashcatcloud/fc-sdk-ios/releases) 获取最新稳定版本。建议固定到具体版本号，避免意外更新。
    </Tip>
  </Step>

  <Step title="获取应用凭证">
    在 Flashduty 控制台的 [应用管理](https://console.flashcat.cloud/rum/apps) 页面：

    1. 创建或选择一个 iOS 应用
    2. 获取以下凭证信息：
       * **Application ID** - 应用唯一标识符
       * **Client Token** - 客户端访问令牌
  </Step>

  <Step title="初始化 SDK">
    在您的 `AppDelegate.swift` 的 `application(_:didFinishLaunchingWithOptions:)` 方法中初始化 SDK：

    ```swift AppDelegate.swift theme={null}
    import UIKit
    import DatadogCore

    @main
    class AppDelegate: UIResponder, UIApplicationDelegate {
        func application(
            _ application: UIApplication,
            didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
        ) -> Bool {
            Datadog.initialize(
                with: Datadog.Configuration(
                    clientToken: "<CLIENT_TOKEN>",
                    env: "<ENV_NAME>"
                ),
                trackingConsent: .granted
            )

            return true
        }
    }
    ```

    <Note>
      **参数说明：**

      * `clientToken` - 从控制台获取的客户端令牌（必填）
      * `env` - 环境名称，如 `production`、`staging`（必填）
      * `trackingConsent` - 用户追踪同意状态（详见下方说明）
    </Note>

    **TrackingConsent 同意状态：**

    | 状态            | 行为                     |
    | ------------- | ---------------------- |
    | `.granted`    | 开始收集数据并发送到 Flashduty   |
    | `.pending`    | 开始收集和批处理数据，但不发送，等待后续确认 |
    | `.notGranted` | 不收集任何数据                |

    <Tip>
      您可以在初始化后通过 `Datadog.set(trackingConsent:)` 动态修改追踪同意状态。
    </Tip>
  </Step>

  <Step title="启用 RUM 功能">
    配置并启用 RUM 功能。建议在 `AppDelegate` 中尽早启用：

    ```swift AppDelegate.swift theme={null}
    import DatadogRUM

    RUM.enable(
        with: RUM.Configuration(
            applicationID: "<RUM_APPLICATION_ID>",
            uiKitViewsPredicate: DefaultUIKitRUMViewsPredicate(),
            uiKitActionsPredicate: DefaultUIKitRUMActionsPredicate(),
            swiftUIViewsPredicate: DefaultSwiftUIRUMViewsPredicate(),
            swiftUIActionsPredicate: DefaultSwiftUIRUMActionsPredicate(
                isLegacyDetectionEnabled: true
            ),
            urlSessionTracking: RUM.Configuration.URLSessionTracking()
        )
    )
    ```

    <Note>
      **配置参数说明：**

      * `applicationID` - 从控制台获取的 RUM 应用 ID
      * `uiKitViewsPredicate` - UIKit 视图追踪策略
      * `uiKitActionsPredicate` - UIKit 用户操作追踪策略
      * `swiftUIViewsPredicate` - SwiftUI 视图追踪策略
      * `swiftUIActionsPredicate` - SwiftUI 用户操作追踪策略
      * `urlSessionTracking` - URLSession 网络请求追踪配置
    </Note>

    <Check>
      SDK 将自动开始收集以下数据：

      * UIKit 和 SwiftUI 视图追踪
      * 用户交互事件
      * 网络请求监控
    </Check>
  </Step>

  <Step title="配置网络追踪（可选）">
    **启用 URLSession 追踪：**

    要监控从 `URLSession` 实例发送的网络请求，需要启用 `URLSessionInstrumentation` 并传入您的 delegate 类型：

    ```swift theme={null}
    import DatadogRUM

    URLSessionInstrumentation.enable(
        with: .init(
            delegateClass: YourSessionDelegate.self
        )
    )

    let session = URLSession(
        configuration: .default,
        delegate: YourSessionDelegate(),
        delegateQueue: nil
    )
    ```

    <Check>
      **自动追踪的网络信息：**

      * 请求 URL、方法、状态码
      * 请求和响应头信息
      * 请求时长和数据大小
      * 网络错误信息
    </Check>

    <Note>
      只有在视图处于活动状态时发起的网络请求才会被追踪。
    </Note>
  </Step>
</Steps>

## 视图追踪

Flashduty iOS SDK 支持自动追踪 UIKit 和 SwiftUI 视图。

### UIKit 视图自动追踪

<Note>
  UIKit 视图会通过 `DefaultUIKitRUMViewsPredicate` 自动追踪。SDK 会追踪 `UIViewController` 的生命周期，自动记录视图的显示和隐藏。
</Note>

### SwiftUI 视图追踪

对于 SwiftUI 应用，需要在视图中添加 `.trackRUMView()` 修饰符：

```swift theme={null}
import SwiftUI
import DatadogRUM

struct ProductView: View {
    var body: some View {
        VStack {
            Text("Product Details")
            // Your view content
        }
        .trackRUMView(name: "Product")
    }
}
```

<Tip>
  `trackRUMView(name:)` 方法会在 SwiftUI 视图出现和消失时自动开始和停止视图追踪。
</Tip>

### 自定义视图追踪

如果需要更精细的控制，可以手动追踪视图：

```swift theme={null}
import DatadogRUM

// 开始追踪视图
RUMMonitor.shared().startView(
    key: "view-key",
    name: "View Name",
    attributes: [:]
)

// 停止追踪视图
RUMMonitor.shared().stopView(
    key: "view-key",
    attributes: [:]
)
```

## 用户操作追踪

### UIKit 操作自动追踪

<Check>
  UIKit 中的用户操作（如点击按钮、切换开关等）会通过 `DefaultUIKitRUMActionsPredicate` 自动追踪。
</Check>

### SwiftUI 操作追踪

对于 SwiftUI 控件，可以添加 `.trackRUMTapAction()` 修饰符：

```swift theme={null}
import SwiftUI
import DatadogRUM

struct CheckoutView: View {
    var body: some View {
        Button("Complete Purchase") {
            // Button action
        }
        .trackRUMTapAction(name: "Purchase")
    }
}
```

<Warning>
  在 `List` 内使用 `.trackRUMTapAction(name:)` 可能会影响默认手势（例如禁用 `Button` 操作或破坏 `NavigationLink`）。对于 `List` 元素，建议使用自定义操作 API。
</Warning>

### 自定义操作追踪

手动追踪用户操作：

```swift theme={null}
import DatadogRUM

RUMMonitor.shared().addAction(
    type: .tap,
    name: "Button Tapped",
    attributes: ["button_id": "submit"]
)
```

## 高级配置

### 追踪错误

Flashduty iOS SDK 会自动捕获应用崩溃和未捕获的异常。您也可以手动记录错误：

```swift theme={null}
import DatadogRUM

RUMMonitor.shared().addError(
    message: "Network request failed",
    type: "NetworkError",
    source: .network,
    attributes: [
        "url": "https://api.example.com",
        "status_code": 500
    ]
)
```

<Check>
  所有错误信息都会在控制台的 RUM Explorer 中显示，包括错误堆栈、属性和 JSON 详情。
</Check>

<Note>
  详细的异常上报配置请参阅 [iOS 异常上报](/zh/rum/error-tracking/erro-reporting/ios)。
</Note>

### 追踪后台事件

您可以追踪应用在后台运行时的事件（例如崩溃和网络请求）：

```swift theme={null}
RUM.enable(
    with: RUM.Configuration(
        applicationID: "<RUM_APPLICATION_ID>",
        trackBackgroundEvents: true
    )
)
```

<Warning>
  追踪后台事件可能会产生额外的会话，从而影响计费。如有疑问，请联系 Flashduty 支持团队。
</Warning>

### 追踪用户信息

您可以为当前会话设置用户信息，便于追踪特定用户的行为：

```swift theme={null}
import DatadogCore

Datadog.setUserInfo(
    id: "user-123",
    name: "John Doe",
    email: "john.doe@example.com",
    extraInfo: [
        "plan": "premium",
        "signup_date": "2024-01-15"
    ]
)
```

<Tip>
  自定义用户属性（如 `plan`、`signup_date`）可用于在分析看板中分组和过滤数据。
</Tip>

### 离线数据处理

iOS SDK 确保在用户设备离线时的数据可用性：

<Check>
  **数据持久化机制：**

  * 网络信号弱或设备电量过低时，事件以批次形式存储在本地
  * 网络恢复后自动上传，确保不丢失数据
  * 自动清理过旧数据，避免占用过多磁盘空间
</Check>

<Note>
  即使用户在离线时使用应用，数据也会被保留并在网络恢复后上传，不会丢失任何监控数据。
</Note>

## WebView 集成

如果您的 iOS 应用中包含 WKWebView，可以启用 WebView 追踪来监控 Web 内容的性能和错误。

<Steps>
  <Step title="添加 WebView 依赖">
    在 Swift Package Manager 添加包依赖时，同时添加 `FlashcatWebViewTracking` 模块。
  </Step>

  <Step title="启用 WebView 追踪">
    在您的 ViewController 中启用 WebView 追踪：

    ```swift theme={null}
    import DatadogWebViewTracking
    import WebKit

    let webView = WKWebView()

    // 为指定的 WKWebView 启用追踪
    WebViewTracking.enable(
        webView: webView,
        hosts: ["example.com", "*.example.com"]
    )
    ```

    <Note>
      **参数说明：**

      * `webView` - 需要追踪的 WKWebView 实例
      * `hosts` - 允许追踪的域名列表，支持通配符（如 `*.example.com`）
    </Note>
  </Step>
</Steps>

<Check>
  WebView 中的 Web 页面现在可以与原生应用的 RUM 数据关联起来。
</Check>

### 禁用自动用户数据收集

为了符合隐私法规或组织数据治理政策，您可以禁用自动收集用户数据。

<Steps>
  <Step title="进入应用管理">
    创建应用后，进入 **应用管理**页面并点击您的应用。
  </Step>

  <Step title="配置数据收集">
    点击 **用户数据收集** 选项，使用开关控制以下设置：

    * 客户端 IP 收集
    * 地理位置数据收集
  </Step>
</Steps>

## 验证接入

接入完成后，验证集成是否成功：

<Steps>
  <Step title="查看控制台日志">
    在 Xcode 控制台中搜索 `Datadog` 关键字，查看 SDK 初始化和数据上报日志。
  </Step>

  <Step title="访问控制台">
    登录 Flashduty 控制台，进入对应的 RUM 应用，查看是否有数据上报。
  </Step>

  <Step title="触发测试事件">
    在应用中执行以下操作验证数据采集：

    * 打开应用的不同页面，验证页面浏览事件
    * 执行用户操作（点击、滑动等），验证交互事件
    * 触发网络请求，验证资源加载事件
    * 手动触发一个错误，验证错误追踪

    <Check>
      如果看到数据上报且控制台中有数据显示，说明集成成功！
    </Check>
  </Step>
</Steps>

## 下一步

<CardGroup cols={2}>
  <Card title="高级配置" icon="sliders" href="/zh/rum/sdk/ios/advanced-config">
    深入配置 SDK 的高级功能，如自定义采样、用户标识、全局上下文等
  </Card>

  <Card title="数据收集" icon="database" href="/zh/rum/sdk/ios/data-collection">
    了解 SDK 收集的数据类型和数据结构
  </Card>

  <Card title="分析看板" icon="chart-line" href="/zh/rum/analytics/native">
    查看和分析应用的性能、错误和用户行为数据
  </Card>

  <Card title="错误追踪" icon="bug" href="/zh/rum/error-tracking/overview">
    配置崩溃报告和异常追踪功能
  </Card>
</CardGroup>