> ## 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 数据收集

> 全面了解 Flashduty iOS RUM SDK 自动收集的性能指标、事件属性和设备信息

<Info>
  iOS RUM SDK 会自动生成包含相关指标和属性的事件。每个 RUM 事件都包含默认属性（如 `view.url`、`device.type`、`geo.country`）以及事件特定的指标和属性（如 `view.time_spent`、`resource.method`）。
</Info>

## 应用启动指标

在应用启动期间，iOS SDK 会自动记录应用启动时间并创建相应的视图。

<Note>
  启动时间测量从进程启动到第一个 `applicationDidBecomeActive` 通知之间的时间间隔。
</Note>

| 属性                    | 类型     | 描述                               |
| --------------------- | ------ | -------------------------------- |
| `view.is_start_view`  | 布尔值    | 标识该视图是否为应用启动时创建的初始视图             |
| `action.type`         | 字符串    | 应用启动操作的类型，值为 `application_start` |
| `action.loading_time` | 数字（纳秒） | 应用启动所需的时间                        |

## 视图监测

在 iOS 应用中，视图会在用户访问不同屏幕时自动创建。当用户打开屏幕时，视图开始记录；当视图不再可见时停止。

<Tip>
  **视图生命周期管理：**

  * 视图停止时不会立即结束，而是保持在 `inactive` 状态一段时间
  * 如果在此期间启动了新视图，之前的视图将完全结束
  * 如果没有新视图启动，之前的视图将恢复为 `active` 状态
</Tip>

<Note>
  **后台行为：**

  * 当应用进入后台时，SDK 会保留最后一个活动视图并监控后台事件
  * 后台时间不会计入活动视图的 `time_spent` 指标
  * 如果用户立即返回应用，SDK 会恢复原始的 `time_spent` 测量
</Note>

## 默认属性

iOS RUM SDK 为所有事件自动附加默认属性，帮助您了解用户设备、网络状态和应用上下文。

<AccordionGroup>
  <Accordion title="通用核心属性">
    | 属性               | 类型  | 描述                                                    |
    | ---------------- | --- | ----------------------------------------------------- |
    | `date`           | 整数  | 事件的时间戳（毫秒）                                            |
    | `type`           | 字符串 | 事件的类型（如 `session`、`view`、`resource`、`error`、`action`） |
    | `service`        | 字符串 | 生成此事件的服务名称                                            |
    | `application.id` | 字符串 | 应用的唯一标识符                                              |
  </Accordion>

  <Accordion title="设备属性">
    以下设备相关属性会自动附加到所有事件上：

    | 属性             | 类型  | 描述                                               |
    | -------------- | --- | ------------------------------------------------ |
    | `device.type`  | 字符串 | 设备类型（如 `Mobile`、`Tablet`、`TV`、`Desktop`、`Other`） |
    | `device.brand` | 字符串 | 设备品牌，iOS 设备为 `Apple`                             |
    | `device.model` | 字符串 | 设备型号（如 `iPhone`、`iPad`、`iPod Touch`、`Apple TV`）  |
    | `device.name`  | 字符串 | 设备的名称                                            |
  </Accordion>

  <Accordion title="操作系统属性">
    以下操作系统相关属性会自动附加到所有事件上：

    | 属性                 | 类型  | 描述                              |
    | ------------------ | --- | ------------------------------- |
    | `os.name`          | 字符串 | 操作系统名称（如 `iOS`、`iPadOS`、`tvOS`） |
    | `os.version`       | 字符串 | 操作系统版本号（如 `15.4.1`、`16.0`）      |
    | `os.version_major` | 字符串 | 操作系统主版本号（如 `15`、`16`）           |
  </Accordion>

  <Accordion title="网络连接属性">
    以下网络相关属性会自动附加到资源和错误事件上：

    | 属性                                   | 类型    | 描述                                        |
    | ------------------------------------ | ----- | ----------------------------------------- |
    | `connectivity.status`                | 字符串   | 设备网络连接状态（如 `connected`、`not_connected`）   |
    | `connectivity.interfaces`            | 字符串数组 | 可用的网络接口类型（如 `wifi`、`cellular`、`ethernet`） |
    | `connectivity.cellular.technology`   | 字符串   | 蜂窝网络技术类型（如 `3G`、`4G`、`LTE`、`5G`）          |
    | `connectivity.cellular.carrier_name` | 字符串   | 蜂窝网络运营商名称                                 |
  </Accordion>

  <Accordion title="地理位置属性">
    以下属性与 IP 地址的地理位置相关：

    | 属性                        | 类型  | 描述                      |
    | ------------------------- | --- | ----------------------- |
    | `geo.country`             | 字符串 | 国家名称                    |
    | `geo.country_iso_code`    | 字符串 | 国家的 ISO 代码（如 `US`、`CN`） |
    | `geo.country_subdivision` | 字符串 | 国家的一级行政区划（如美国的州、中国的省）   |
    | `geo.continent_code`      | 字符串 | 洲的 ISO 代码（如 `EU`、`AS`）  |
    | `geo.continent`           | 字符串 | 洲名称                     |
    | `geo.city`                | 字符串 | 城市名称                    |

    <Note>
      地理位置信息由 Flashduty 后端根据客户端 IP 地址推断，不会在客户端收集精确的 GPS 位置。
    </Note>
  </Accordion>

  <Accordion title="全局用户属性">
    您可以在所有 RUM 事件上启用用户追踪，以关联用户会话并简化问题排查。

    | 属性          | 类型  | 描述                      |
    | ----------- | --- | ----------------------- |
    | `usr.id`    | 字符串 | 用户的唯一标识符                |
    | `usr.name`  | 字符串 | 用户友好名称，默认显示在 RUM UI 中   |
    | `usr.email` | 字符串 | 用户电子邮件地址，如果没有用户名则显示电子邮件 |

    <Tip>
      用户属性是可选的，但建议至少提供一个。详见 [追踪用户信息](/zh/rum/sdk/ios/sdk-integration#追踪用户信息)。
    </Tip>
  </Accordion>
</AccordionGroup>

## 事件特定属性

不同的事件类型具有特定的属性和指标。

<AccordionGroup>
  <Accordion title="会话属性">
    | 属性                          | 类型  | 描述                          |
    | --------------------------- | --- | --------------------------- |
    | `session.id`                | 字符串 | 会话的唯一标识符。                   |
    | `session.type`              | 字符串 | 会话类型（如 `user`、`synthetic`）。 |
    | `session.is_active`         | 布尔值 | 会话是否处于活动状态。                 |
    | `session.initial_view.id`   | 字符串 | 会话中初始视图的 ID。                |
    | `session.initial_view.url`  | 字符串 | 会话中初始视图的 URL。               |
    | `session.initial_view.name` | 字符串 | 会话中初始视图的名称。                 |
    | `session.last_view.id`      | 字符串 | 会话中最后一个视图的 ID。              |
    | `session.last_view.url`     | 字符串 | 会话中最后一个视图的 URL。             |
    | `session.last_view.name`    | 字符串 | 会话中最后一个视图的名称。               |
    | `session.has_crash`         | 布尔值 | 会话是否包含崩溃事件                  |
    | `session.has_replay`        | 布尔值 | 会话是否启用了会话重放                 |
  </Accordion>

  <Accordion title="视图属性">
    | 属性                          | 类型     | 描述                              |
    | --------------------------- | ------ | ------------------------------- |
    | `view.id`                   | 字符串    | 视图的唯一标识符。                       |
    | `view.url`                  | 字符串    | 视图的 URL，对应 UIViewController 类名。 |
    | `view.name`                 | 字符串    | 视图的可自定义名称。                      |
    | `view.referrer`             | 字符串    | 前一个视图的 URL。                     |
    | `view.action.count`         | 数字     | 该视图中收集的用户操作数。                   |
    | `view.error.count`          | 数字     | 该视图中收集的错误数。                     |
    | `view.resource.count`       | 数字     | 该视图中收集的资源数。                     |
    | `view.time_spent`           | 数字（纳秒） | 用户在该视图上花费的时间。                   |
    | `view.network_settled_time` | 数字（纳秒） | 视图启动时完全初始化所需的时间。                |
    | `view.is_active`            | 布尔值    | 视图是否处于活动状态。                     |
    | `view.is_slow_rendered`     | 布尔值    | 视图渲染是否缓慢。                       |
    | `view.crash.count`          | 数字     | 该视图中发生的崩溃数。                     |
    | `view.frozen_frame.count`   | 数字     | 该视图中的冻结帧数。                      |
    | `view.refresh_rate_average` | 数字     | 视图的平均刷新率。                       |
    | `view.refresh_rate_min`     | 数字     | 视图的最低刷新率。                       |
    | `view.memory_average`       | 数字     | 视图的平均内存使用量。                     |
    | `view.memory_max`           | 数字     | 视图的最大内存使用量。                     |
    | `view.cpu_ticks_count`      | 数字     | 视图的 CPU 时钟周期数                   |
    | `view.cpu_ticks_per_second` | 数字     | 视图每秒的 CPU 时钟周期数                 |
  </Accordion>

  <Accordion title="资源属性">
    | 属性                             | 类型     | 描述                                                |
    | ------------------------------ | ------ | ------------------------------------------------- |
    | `resource.id`                  | 字符串    | 资源的唯一标识符。                                         |
    | `resource.url`                 | 字符串    | 资源 URL。                                           |
    | `resource.method`              | 字符串    | HTTP 方法（如 `GET`、`POST`、`PATCH`、`DELETE`）。         |
    | `resource.type`                | 字符串    | 资源类型（如 `xhr`、`image`、`font`、`css`、`js`）。          |
    | `resource.status_code`         | 数字     | HTTP 响应状态码。                                       |
    | `resource.size`                | 数字（字节） | 资源大小。                                             |
    | `resource.duration`            | 数字（纳秒） | 加载资源所需的总时间。                                       |
    | `resource.connect.duration`    | 数字（纳秒） | 建立服务器连接所需的时间（connectEnd - connectStart）。          |
    | `resource.ssl.duration`        | 数字（纳秒） | TLS 握手所需的时间。                                      |
    | `resource.dns.duration`        | 数字（纳秒） | DNS 解析所需的时间（domainLookupEnd - domainLookupStart）。 |
    | `resource.first_byte.duration` | 数字（纳秒） | 等待接收响应首字节的时间（responseStart - requestStart）。       |
    | `resource.download.duration`   | 数字（纳秒） | 下载响应的时间（responseEnd - responseStart）。             |
    | `resource.redirect.duration`   | 数字（纳秒） | 后续 HTTP 请求所需的时间（redirectEnd - redirectStart）。     |
    | `resource.provider.name`       | 字符串    | 资源提供者名称，默认为 `unknown`。                            |
    | `resource.provider.domain`     | 字符串    | 资源提供者域名                                           |
    | `resource.provider.type`       | 字符串    | 资源提供者类型（如 `first-party`、`cdn`、`ad`、`analytics`）   |
  </Accordion>

  <Accordion title="错误属性">
    错误事件收集异常和崩溃信息，错误消息和堆栈跟踪会被自动包含：

    | 属性                | 类型     | 描述                                                                                               |
    | ----------------- | ------ | ------------------------------------------------------------------------------------------------ |
    | `error.source`    | 字符串    | 错误来源（如 `webview`、`logger`、`network`）。                                                            |
    | `error.type`      | 字符串    | 错误类型（在某些情况下为错误代码）。                                                                               |
    | `error.message`   | 字符串    | 简洁、易读的单行错误消息。                                                                                    |
    | `error.stack`     | 字符串    | 错误的堆栈跟踪或补充信息。                                                                                    |
    | `error.issue_id`  | 字符串    | 错误问题的唯一标识符。                                                                                      |
    | `error.category`  | 字符串    | 错误类型的高级分组。可能的值包括：`ANR`、`App Hang`、`Exception`、`Watchdog Termination`、`Memory Warning`、`Network`。 |
    | `error.file`      | 字符串    | 错误追踪发现问题的文件。                                                                                     |
    | `error.is_crash`  | 布尔值    | 该错误是否导致应用崩溃                                                                                      |
    | `freeze.duration` | 数字（纳秒） | 主线程冻结的持续时间（仅适用于 App Hang）                                                                        |

    **网络错误：**

    网络错误包含有关失败 HTTP 请求的信息，额外收集以下属性：

    | 属性                               | 类型  | 描述                                              |
    | -------------------------------- | --- | ----------------------------------------------- |
    | `error.resource.status_code`     | 数字  | HTTP 响应状态码。                                     |
    | `error.resource.method`          | 字符串 | HTTP 方法（如 `GET`、`POST`）。                        |
    | `error.resource.url`             | 字符串 | 资源 URL。                                         |
    | `error.resource.provider.name`   | 字符串 | 资源提供者名称，默认为 `unknown`。                          |
    | `error.resource.provider.domain` | 字符串 | 资源提供者域名                                         |
    | `error.resource.provider.type`   | 字符串 | 资源提供者类型（如 `first-party`、`cdn`、`ad`、`analytics`） |
  </Accordion>

  <Accordion title="操作属性">
    | 属性                       | 类型     | 描述                                   |
    | ------------------------ | ------ | ------------------------------------ |
    | `action.id`              | 字符串    | 用户操作的唯一标识符。                          |
    | `action.type`            | 字符串    | 用户操作类型（如 `tap`、`application_start`）。 |
    | `action.name`            | 字符串    | 用户操作的名称。                             |
    | `action.target.name`     | 字符串    | 用户交互的元素（仅适用于自动收集的操作）                 |
    | `action.loading_time`    | 数字（纳秒） | 操作的加载时间                              |
    | `action.resource.count`  | 数字     | 该操作触发的资源数                            |
    | `action.error.count`     | 数字     | 该操作触发的错误数                            |
    | `action.long_task.count` | 数字     | 该操作触发的长任务数                           |
  </Accordion>

  <Accordion title="崩溃属性">
    当应用发生崩溃时，会收集以下额外属性：

    | 属性                    | 类型  | 描述                               |
    | --------------------- | --- | -------------------------------- |
    | `error.signal`        | 字符串 | 导致崩溃的信号名称（如 `SIGABRT`、`SIGSEGV`） |
    | `error.binary_images` | 数组  | 崩溃时加载的二进制映像列表                    |
    | `error.threads`       | 数组  | 崩溃时所有线程的状态                       |
    | `error.meta`          | 对象  | 崩溃相关的元数据                         |
  </Accordion>
</AccordionGroup>

## 数据存储与安全

### 本地存储机制

在上传到 Flashduty 之前，数据以明文形式存储在应用沙盒的缓存目录（`Library/Caches`）中。

<Check>
  **安全保护：**

  * 缓存目录受 iOS 应用沙盒保护
  * 设备上安装的其他应用无法读取此目录
</Check>

### 数据管理策略

为确保 SDK 不会占用过多磁盘空间，SDK 会自动管理本地数据：

| 策略       | 说明                        |
| -------- | ------------------------- |
| **智能上传** | 当网络可用且设备电量充足时，数据以批次形式发送   |
| **失败重试** | 如果网络不可用或上传失败，批次会被保留直到成功发送 |
| **自动清理** | 超过一定时限的数据会被自动清理           |

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

## 相关文档

<CardGroup cols={3}>
  <Card title="SDK 接入" icon="plug" href="/zh/rum/sdk/ios/sdk-integration">
    了解如何集成 iOS SDK
  </Card>

  <Card title="高级配置" icon="sliders" href="/zh/rum/sdk/ios/advanced-config">
    配置自定义属性、采样和事件过滤
  </Card>

  <Card title="兼容性" icon="check" href="/zh/rum/sdk/ios/compatible">
    了解 SDK 兼容性要求
  </Card>
</CardGroup>