> ## 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.

# Web SDK 数据收集

> 详细了解 Web RUM SDK 收集的数据类型、事件属性、性能指标以及数据存储机制

<Info>
  Web RUM SDK 自动收集丰富的用户行为和性能数据。每个 RUM 事件都包含默认属性（如 `view.url`、`device.type`、`geo.country`）以及特定事件类型的附加指标和属性。
</Info>

## 默认属性

Web RUM SDK 会自动捕获以下默认属性，这些属性适用于所有 RUM 事件类型。

<AccordionGroup>
  <Accordion title="通用核心属性">
    | 属性               | 类型  | 描述                                                    |
    | ---------------- | --- | ----------------------------------------------------- |
    | `date`           | 整数  | 事件的时间戳（以毫秒为单位，epoch 毫秒）                               |
    | `type`           | 字符串 | 事件的类型（如 `session`、`view`、`resource`、`error`、`action`） |
    | `application.id` | 字符串 | 应用的唯一标识符                                              |
    | `service`        | 字符串 | 生成此事件的服务名称                                            |
    | `env`            | 字符串 | 应用的环境名称（如 `prod`、`dev`、`staging`）                     |
    | `version`        | 字符串 | 应用版本                                                  |
    | `sdk_version`    | 字符串 | RUM SDK 版本                                            |
  </Accordion>

  <Accordion title="设备属性">
    | 属性             | 类型  | 描述                                               |
    | -------------- | --- | ------------------------------------------------ |
    | `device.type`  | 字符串 | 设备类型（如 `Desktop`、`Mobile`、`Tablet`、`TV`、`Other`） |
    | `device.brand` | 字符串 | 设备品牌（如 `Apple`、`Samsung`、`Huawei`）               |
    | `device.model` | 字符串 | 设备型号（如 `iPhone`、`iPad`）                          |
    | `device.name`  | 字符串 | 设备的商业名称                                          |
  </Accordion>

  <Accordion title="操作系统属性">
    | 属性                 | 类型  | 描述                                 |
    | ------------------ | --- | ---------------------------------- |
    | `os.name`          | 字符串 | 操作系统名称（如 `Mac OS`、`Windows`、`iOS`） |
    | `os.version`       | 字符串 | 操作系统版本号（如 `10.15.7`、`11.0`）        |
    | `os.version_major` | 字符串 | 操作系统主版本号（如 `10`、`11`）              |
  </Accordion>

  <Accordion title="浏览器属性">
    | 属性                        | 类型  | 描述                                          |
    | ------------------------- | --- | ------------------------------------------- |
    | `browser.name`            | 字符串 | 浏览器名称（如 `Chrome`、`Firefox`、`Safari`、`Edge`） |
    | `browser.version`         | 字符串 | 浏览器版本号（如 `91.0.4472.124`）                   |
    | `browser.version_major`   | 字符串 | 浏览器主版本号（如 `91`）                             |
    | `browser.user_agent`      | 字符串 | User Agent 字符串                              |
    | `browser.viewport.width`  | 数字  | 浏览器视口宽度（像素）                                 |
    | `browser.viewport.height` | 数字  | 浏览器视口高度（像素）                                 |
  </Accordion>

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

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

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

    <Tip>
      您还可以添加自定义用户属性，例如 `usr.plan`、`usr.role` 等。要设置用户信息，请参阅 [SDK 接入指南](/zh/rum/sdk/web/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_replay`        | 布尔值 | 会话是否启用了会话重放                |
  </Accordion>

  <Accordion title="视图时间指标">
    RUM 收集来自 [Navigation Timing API](https://www.w3.org/TR/navigation-timing/) 的所有性能指标，以及与 [Core Web Vitals](https://web.dev/vitals/) 相关的指标。

    **Core Web Vitals**

    | 属性                               | 类型     | 描述                                    |
    | -------------------------------- | ------ | ------------------------------------- |
    | `view.largest_contentful_paint`  | 数字（纳秒） | 最大内容绘制时间（LCP），视口中最大可见内容元素的渲染时间        |
    | `view.first_input_delay`         | 数字（纳秒） | 首次输入延迟（FID），用户首次与页面交互到浏览器实际响应该交互之间的时间 |
    | `view.cumulative_layout_shift`   | 数字     | 累积布局偏移（CLS），量化了视口内可见元素的意外移动           |
    | `view.interaction_to_next_paint` | 数字（纳秒） | 交互到下次绘制（INP），测量用户与页面进行所有交互的延迟         |

    **导航性能指标**

    | 属性                            | 类型     | 描述                                                |
    | ----------------------------- | ------ | ------------------------------------------------- |
    | `view.time_spent`             | 数字（纳秒） | 用户在该视图上花费的时间                                      |
    | `view.loading_time`           | 数字（纳秒） | 页面完全加载所需的时间（`loadEventEnd` 时触发）                   |
    | `view.first_contentful_paint` | 数字（纳秒） | 首次内容绘制时间（FCP），浏览器首次渲染任何文本、图像、非空白 canvas 或 SVG 的时间 |
    | `view.first_byte`             | 数字（纳秒） | 首字节时间（TTFB），从用户发起页面加载到浏览器接收 HTML 文档第一个字节的时间       |
    | `view.dom_interactive`        | 数字（纳秒） | 解析器完成对主文档的工作的时刻（`domInteractive`）                 |
    | `view.dom_content_loaded`     | 数字（纳秒） | 初始 HTML 文档完全加载和解析的时间                              |
    | `view.dom_complete`           | 数字（纳秒） | 页面和所有子资源准备就绪的时间（`domComplete`）                    |
    | `view.load_event`             | 数字（纳秒） | 触发 load 事件的时间（`loadEventEnd`），表示页面完全加载            |

    **网络耗时指标**

    | 属性                                    | 类型     | 描述               |
    | ------------------------------------- | ------ | ---------------- |
    | `view.redirect.duration`              | 数字（纳秒） | 重定向所花费的时间        |
    | `view.dns.duration`                   | 数字（纳秒） | DNS 查询所花费的时间     |
    | `view.connect.duration`               | 数字（纳秒） | 建立服务器连接所花费的时间    |
    | `view.ssl.duration`                   | 数字（纳秒） | TLS 握手所花费的时间     |
    | `view.request.duration`               | 数字（纳秒） | 请求 HTML 文档所花费的时间 |
    | `view.response.duration`              | 数字（纳秒） | 下载 HTML 文档所花费的时间 |
    | `view.in_foreground_periods.count`    | 数字     | 视图处于前台的次数        |
    | `view.in_foreground_periods.duration` | 数字（纳秒） | 视图处于前台的总时间       |
  </Accordion>

  <Accordion title="视图属性">
    | 属性                     | 类型  | 描述                   |
    | ---------------------- | --- | -------------------- |
    | `view.id`              | 字符串 | 视图的唯一标识符             |
    | `view.url`             | 字符串 | 视图的 URL              |
    | `view.name`            | 字符串 | 视图的可自定义名称            |
    | `view.referrer`        | 字符串 | 前一个页面的 URL（referrer） |
    | `view.action.count`    | 数字  | 该视图中收集的用户操作数         |
    | `view.error.count`     | 数字  | 该视图中收集的错误数           |
    | `view.resource.count`  | 数字  | 该视图中收集的资源数           |
    | `view.long_task.count` | 数字  | 该视图中收集的长任务数          |
    | `view.is_active`       | 布尔值 | 视图是否处于活动状态           |
  </Accordion>

  <Accordion title="资源时间指标">
    RUM 会收集来自 [Resource Timing API](https://www.w3.org/TR/resource-timing-2/) 的详细网络时间信息，用于单个资源的加载。

    | 属性                                | 类型     | 描述                                   |
    | --------------------------------- | ------ | ------------------------------------ |
    | `resource.duration`               | 数字（纳秒） | 加载资源所需的总时间                           |
    | `resource.size`                   | 数字（字节） | 资源大小                                 |
    | `resource.connect.duration`       | 数字（纳秒） | 建立服务器连接所需的时间                         |
    | `resource.ssl.duration`           | 数字（纳秒） | TLS 握手所需的时间（仅 HTTPS）                 |
    | `resource.dns.duration`           | 数字（纳秒） | DNS 解析所需的时间                          |
    | `resource.redirect.duration`      | 数字（纳秒） | 重定向所需的时间                             |
    | `resource.first_byte.duration`    | 数字（纳秒） | 等待接收响应首字节的时间                         |
    | `resource.download.duration`      | 数字（纳秒） | 下载响应的时间                              |
    | `resource.render_blocking_status` | 字符串    | 资源的渲染阻塞状态（`blocking`、`non-blocking`） |
    | `resource.first_party`            | 布尔值    | 是否为第一方资源（与应用同域）                      |
  </Accordion>

  <Accordion title="资源属性">
    | 属性                         | 类型  | 描述                                                       |
    | -------------------------- | --- | -------------------------------------------------------- |
    | `resource.id`              | 字符串 | 资源的唯一标识符                                                 |
    | `resource.type`            | 字符串 | 资源类型（如 `xhr`、`fetch`、`css`、`js`、`image`、`font`、`media`）  |
    | `resource.method`          | 字符串 | HTTP 方法（如 `GET`、`POST`、`PUT`、`DELETE`）                   |
    | `resource.status_code`     | 数字  | HTTP 响应状态码                                               |
    | `resource.url`             | 字符串 | 资源 URL                                                   |
    | `resource.url_host`        | 字符串 | URL 的主机部分                                                |
    | `resource.url_path`        | 字符串 | URL 的路径部分                                                |
    | `resource.url_query`       | 对象  | URL 的查询参数，以键值对形式解析                                       |
    | `resource.url_scheme`      | 字符串 | URL 的协议（如 `https`、`http`）                                |
    | `resource.provider.name`   | 字符串 | 资源提供者名称，默认为 `unknown`                                    |
    | `resource.provider.domain` | 字符串 | 资源提供者域名                                                  |
    | `resource.provider.type`   | 字符串 | 资源提供者类型（如 `first-party`、`cdn`、`ad`、`analytics`、`social`） |
  </Accordion>

  <Accordion title="GraphQL 属性">
    如果启用了 GraphQL 请求追踪，以下属性会附加到 `resource` 事件上：

    | 属性                                | 类型  | 描述                                                |
    | --------------------------------- | --- | ------------------------------------------------- |
    | `resource.graphql.operation_type` | 字符串 | GraphQL 操作类型（`query`、`mutation`、`subscription`）   |
    | `resource.graphql.operation_name` | 字符串 | GraphQL 操作名称（如果在请求中提供）                            |
    | `resource.graphql.variables`      | 字符串 | 随请求发送的 GraphQL 变量                                 |
    | `resource.graphql.payload`        | 字符串 | GraphQL 查询（限制为 32 KB，仅在启用 `trackPayload` 时可用）     |
    | `resource.graphql.errors_count`   | 数字  | GraphQL 响应中返回的错误数（仅在启用 `trackResponseErrors` 时可用） |
    | `resource.graphql.errors`         | 数组  | GraphQL 错误数组，包含 message、code、locations 和 path     |
  </Accordion>

  <Accordion title="长任务属性">
    长任务是指阻塞主线程 50 毫秒或更长时间的任务。这些任务会导致高输入延迟、慢速交互或卡顿的动画/滚动。

    | 属性                          | 类型     | 描述                   |
    | --------------------------- | ------ | -------------------- |
    | `long_task.duration`        | 数字（纳秒） | 长任务的持续时间             |
    | `long_task.is_frozen_frame` | 布尔值    | 是否为冻结帧（持续时间超过 700ms） |

    <Warning>
      长任务检测仅在支持 Long Tasks API 的浏览器中可用（Chrome、Edge）。Safari 和 Firefox 不支持此功能。
    </Warning>
  </Accordion>

  <Accordion title="错误属性">
    前端错误通过 RUM 收集。错误消息和堆栈跟踪（如果可用）会包含在内。

    **通用错误属性**

    | 属性                     | 类型  | 描述                                                                                |
    | ---------------------- | --- | --------------------------------------------------------------------------------- |
    | `error.id`             | 字符串 | 错误的唯一标识符                                                                          |
    | `error.source`         | 字符串 | 错误来源（如 `console`、`network`、`source`、`logger`、`agent`、`webview`、`custom`、`report`） |
    | `error.type`           | 字符串 | 错误类型（在某些情况下为错误代码）                                                                 |
    | `error.message`        | 字符串 | 简洁、易读的单行错误消息                                                                      |
    | `error.stack`          | 字符串 | 错误的堆栈跟踪或补充信息                                                                      |
    | `error.issue_id`       | 字符串 | 错误问题的唯一标识符（相同错误会被聚合到同一 issue）                                                     |
    | `error.fingerprint`    | 字符串 | 用于唯一标识错误的指纹                                                                       |
    | `error.handling`       | 字符串 | 错误处理方式（`handled`、`unhandled`）                                                     |
    | `error.handling_stack` | 字符串 | 错误处理时的堆栈跟踪                                                                        |
    | `error.causes`         | 数组  | 导致此错误的其他错误信息                                                                      |

    **网络错误属性**

    网络错误包含有关失败 HTTP 请求的信息：

    | 属性                               | 类型  | 描述                                              |
    | -------------------------------- | --- | ----------------------------------------------- |
    | `error.resource.status_code`     | 数字  | HTTP 响应状态码                                      |
    | `error.resource.method`          | 字符串 | HTTP 方法（如 `GET`、`POST`）                         |
    | `error.resource.url`             | 字符串 | 资源 URL                                          |
    | `error.resource.url_host`        | 字符串 | URL 的主机部分                                       |
    | `error.resource.url_path`        | 字符串 | URL 的路径部分                                       |
    | `error.resource.url_scheme`      | 字符串 | URL 的协议                                         |
    | `error.resource.provider.name`   | 字符串 | 资源提供者名称，默认为 `unknown`                           |
    | `error.resource.provider.domain` | 字符串 | 资源提供者域名                                         |
    | `error.resource.provider.type`   | 字符串 | 资源提供者类型（如 `first-party`、`cdn`、`ad`、`analytics`） |

    <Tip>
      有关不同 JavaScript 错误类型的更多信息，请参阅 [MDN 文档](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error)。
    </Tip>
  </Accordion>

  <Accordion title="操作属性">
    **操作时间属性**

    | 属性                       | 类型     | 描述         |
    | ------------------------ | ------ | ---------- |
    | `action.loading_time`    | 数字（纳秒） | 操作的加载时间    |
    | `action.long_task.count` | 数字     | 该操作触发的长任务数 |
    | `action.resource.count`  | 数字     | 该操作触发的资源数  |
    | `action.error.count`     | 数字     | 该操作触发的错误数  |

    **操作标识属性**

    | 属性                   | 类型  | 描述                                                         |
    | -------------------- | --- | ---------------------------------------------------------- |
    | `action.id`          | 字符串 | 用户操作的唯一标识符（UUID）                                           |
    | `action.type`        | 字符串 | 用户操作类型（如 `click`、`custom`）。对于自定义用户操作，设置为 `custom`          |
    | `action.target.name` | 字符串 | 用户交互的元素。仅适用于自动收集的操作                                        |
    | `action.name`        | 字符串 | 用户友好的名称（如 `Click on #checkout`）。对于自定义用户操作，为 API 调用中给定的操作名称 |
  </Accordion>

  <Accordion title="挫败信号（Frustration Signals）">
    RUM 会自动检测用户的挫败信号，帮助您了解用户在应用中遇到的问题。

    | 属性                                    | 类型  | 描述                        |
    | ------------------------------------- | --- | ------------------------- |
    | `session.frustration.count`           | 数字  | 会话中所有挫败信号的数量              |
    | `view.frustration.count`              | 数字  | 视图中所有挫败信号的数量              |
    | `action.frustration.type:dead_click`  | 字符串 | RUM SDK 检测到的死点击（点击无响应）    |
    | `action.frustration.type:rage_click`  | 字符串 | RUM SDK 检测到的暴怒点击（连续快速点击）  |
    | `action.frustration.type:error_click` | 字符串 | RUM SDK 检测到的错误点击（点击后触发错误） |

    <Info>
      挫败信号是识别用户体验问题的重要指标。死点击和暴怒点击通常表明 UI 响应不及时或交互设计存在问题。
    </Info>
  </Accordion>

  <Accordion title="UTM 属性">
    如果 URL 中包含 UTM 参数，RUM 会自动捕获以下属性，用于追踪营销活动：

    | 属性                            | 类型  | 描述                        |
    | ----------------------------- | --- | ------------------------- |
    | `view.url_query.utm_source`   | 字符串 | URL 中追踪流量来源的参数            |
    | `view.url_query.utm_medium`   | 字符串 | URL 中追踪流量来自哪个渠道的参数        |
    | `view.url_query.utm_campaign` | 字符串 | URL 中标识与该视图关联的特定营销活动的参数   |
    | `view.url_query.utm_content`  | 字符串 | URL 中标识用户在营销活动中点击的特定元素的参数 |
    | `view.url_query.utm_term`     | 字符串 | URL 中追踪用户搜索以触发给定活动的关键字的参数 |
  </Accordion>
</AccordionGroup>

## 数据存储

在上传到 FlashCat 之前，数据会以明文形式临时存储在浏览器的本地存储（LocalStorage 或 SessionStorage）中。

<Steps>
  <Step title="数据收集">
    SDK 将事件添加到内存中的批次缓冲区。
  </Step>

  <Step title="本地缓存">
    当网络不可用时，批次会被保留在本地存储中。
  </Step>

  <Step title="批次上传">
    网络可用时，数据以批次形式发送到服务器。
  </Step>

  <Step title="自动清理">
    超过一定时限的数据会被自动清理，以避免占用过多存储空间。
  </Step>
</Steps>

<Warning>
  敏感数据不应包含在 RUM 事件中，或者应在发送前通过 `beforeSend` 回调进行混淆或过滤。
</Warning>

## 数据上传

Web RUM SDK 会将收集到的事件以批次形式上传到服务器，以优化网络性能和减少对用户体验的影响。

### 批次上传触发条件

* 批次中的事件数量达到阈值
* 批次大小达到阈值
* 定期上传（例如每 10 秒）
* 页面卸载时（`beforeunload` 事件）

### 上传策略

| 策略                     | 说明                                              |
| ---------------------- | ----------------------------------------------- |
| **Beacon API**         | 优先使用，确保在页面卸载时数据不会丢失                             |
| **XHR/Fetch Fallback** | 如果 Beacon API 不可用，使用 XMLHttpRequest 或 Fetch API |
| **失败重试**               | 如果上传失败，批次会被保留在本地存储，直到成功发送                       |
| **数据压缩**               | 上传前对批次数据进行压缩，减少网络流量                             |

## 隐私和合规

<CardGroup cols={2}>
  <Card title="IP 地址匿名化" icon="eye-slash">
    可配置 SDK 对 IP 地址进行匿名化处理
  </Card>

  <Card title="敏感数据过滤" icon="filter">
    使用 `beforeSend` 回调过滤或混淆敏感信息
  </Card>

  <Card title="Cookie 和存储控制" icon="cookie">
    可配置是否使用 Cookie 和本地存储
  </Card>

  <Card title="GDPR/CCPA 合规" icon="shield-check">
    支持用户隐私选择退出机制
  </Card>
</CardGroup>

<Tip>
  有关隐私配置的详细信息，请参阅 [高级配置](/zh/rum/sdk/web/advanced-config#用户跟踪同意)。
</Tip>

## 更多信息

<CardGroup cols={3}>
  <Card title="SDK 接入" icon="plug" href="/zh/rum/sdk/web/sdk-integration">
    了解如何在 Web 应用中接入 RUM SDK
  </Card>

  <Card title="高级配置" icon="sliders" href="/zh/rum/sdk/web/advanced-config">
    了解如何配置 SDK 的高级功能
  </Card>

  <Card title="兼容性" icon="browser" href="/zh/rum/sdk/web/compatible">
    了解 SDK 的浏览器和框架兼容性
  </Card>
</CardGroup>