数据收集

概述

FlashCat Web RUM SDK 会生成包含相关指标和属性的事件。每个 RUM 事件都包含默认属性,例如事件对应的页面 URL（view.url）和用户信息,如设备类型（device.type）和国家（geo.country）。

此外,不同事件类型还具有特定的附加指标和属性。例如,view.loading_time 指标与视图事件相关联,而 resource.method 属性与资源事件相关联。

默认属性

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

通用核心属性

属性	类型	描述
`date`	整数	事件的时间戳（以毫秒为单位,epoch 毫秒）。
`type`	字符串	事件的类型（如 `session`、`view`、`resource`、`error`、`action`）。
`application.id`	字符串	应用的唯一标识符。
`service`	字符串	生成此事件的服务名称。
`env`	字符串	应用的环境名称（如 `prod`、`dev`、`staging`）。
`version`	字符串	应用版本。
`sdk_version`	字符串	FlashCat RUM SDK 版本。

设备

以下设备相关属性会自动附加到 FlashCat 收集的所有事件上：

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

操作系统

以下操作系统相关属性会自动附加到 FlashCat 收集的所有事件上：

属性	类型	描述
`os.name`	字符串	操作系统名称（如 `Mac OS`、`Windows`、`iOS`）。
`os.version`	字符串	操作系统版本号（如 `10.15.7`、`11.0`）。
`os.version_major`	字符串	操作系统主版本号（如 `10`、`11`）。

浏览器

以下浏览器相关属性会自动附加到所有 Web RUM 事件上：

属性	类型	描述
`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`	数字	浏览器视口高度（像素）。

地理位置

以下属性与 IP 地址的地理位置相关：

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

注意：地理位置信息由 FlashCat 后端根据客户端 IP 地址推断,不会在客户端收集精确的 GPS 位置。

全局用户属性

您可以在所有 RUM 事件上启用用户追踪,以关联用户会话并简化问题排查。用户属性是可选的,但建议提供以下属性：

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

您还可以添加自定义用户属性,例如 usr.plan、usr.role 等。

要设置用户信息,请参阅追踪用户信息。

事件特定属性

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

会话属性

属性	类型	描述
`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`	布尔值	会话是否启用了会话重放。

视图时间指标

FlashCat RUM 收集来自 Navigation Timing API 的所有性能指标,以及与 Core Web Vitals 相关的指标。

属性	类型	描述
`view.time_spent`	数字（纳秒）	用户在该视图上花费的时间。
`view.loading_time`	数字（纳秒）	页面完全加载所需的时间（`loadEventEnd` 时触发）。
`view.largest_contentful_paint`	数字（纳秒）	最大内容绘制时间（LCP），视口中最大可见内容元素的渲染时间。
`view.first_input_delay`	数字（纳秒）	首次输入延迟（FID），用户首次与页面交互到浏览器实际响应该交互之间的时间。
`view.cumulative_layout_shift`	数字	累积布局偏移（CLS），量化了视口内可见元素的意外移动。
`view.interaction_to_next_paint`	数字（纳秒）	交互到下次绘制（INP），测量用户与页面进行所有交互的延迟。
`view.first_contentful_paint`	数字（纳秒）	首次内容绘制时间（FCP），浏览器首次渲染任何文本、图像、非空白 canvas 或 SVG 的时间。
`view.dom_interactive`	数字（纳秒）	解析器完成对主文档的工作的时刻（`domInteractive`）。
`view.dom_content_loaded`	数字（纳秒）	初始 HTML 文档完全加载和解析的时间,无需等待样式表、图像和子框架完成加载（`domContentLoadedEventEnd`）。
`view.dom_complete`	数字（纳秒）	页面和所有子资源准备就绪的时间（`domComplete`）。
`view.load_event`	数字（纳秒）	触发 load 事件的时间（`loadEventEnd`），表示页面完全加载。
`view.first_byte`	数字（纳秒）	首字节时间（TTFB），从用户发起页面加载到浏览器接收 HTML 文档第一个字节的时间（`responseStart`）。
`view.redirect.duration`	数字（纳秒）	重定向所花费的时间（`redirectEnd - redirectStart`）。
`view.dns.duration`	数字（纳秒）	DNS 查询所花费的时间（`domainLookupEnd - domainLookupStart`）。
`view.connect.duration`	数字（纳秒）	建立服务器连接所花费的时间（`connectEnd - connectStart`）。
`view.ssl.duration`	数字（纳秒）	TLS 握手所花费的时间（`connectEnd - secureConnectionStart`）。
`view.request.duration`	数字（纳秒）	请求 HTML 文档所花费的时间（`responseStart - requestStart`）。
`view.response.duration`	数字（纳秒）	下载 HTML 文档所花费的时间（`responseEnd - responseStart`）。
`view.in_foreground_periods.count`	数字	视图处于前台的次数。
`view.in_foreground_periods.duration`	数字（纳秒）	视图处于前台的总时间。

视图属性

属性	类型	描述
`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`	布尔值	视图是否处于活动状态。

资源时间指标

FlashCat RUM 会收集来自 Resource Timing API 的详细网络时间信息,用于单个资源的加载。

属性	类型	描述
`resource.duration`	数字（纳秒）	加载资源所需的总时间。
`resource.size`	数字（字节）	资源大小。
`resource.connect.duration`	数字（纳秒）	建立服务器连接所需的时间（`connectEnd - connectStart`）。
`resource.ssl.duration`	数字（纳秒）	TLS 握手所需的时间。如果最后一个请求不是通过 HTTPS,则不会出现此指标。
`resource.dns.duration`	数字（纳秒）	DNS 解析所需的时间（`domainLookupEnd - domainLookupStart`）。
`resource.redirect.duration`	数字（纳秒）	后续 HTTP 请求所需的时间（`redirectEnd - redirectStart`）。
`resource.first_byte.duration`	数字（纳秒）	等待接收响应首字节的时间（`responseStart - requestStart`）。
`resource.download.duration`	数字（纳秒）	下载响应的时间（`responseEnd - responseStart`）。
`resource.render_blocking_status`	字符串	资源的渲染阻塞状态（`blocking`、`non-blocking`）。
`resource.first_party`	布尔值	是否为第一方资源（与应用同域）。

资源属性

属性	类型	描述
`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`）。

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（仅在启用 `trackResponseErrors` 时可用）。

长任务时间属性

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

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

错误属性

前端错误通过 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`	数组	导致此错误的其他错误信息。

源错误

源错误包含有关错误的代码级信息。有关不同错误类型的更多信息,请参阅 MDN 文档。

属性	类型	描述
`error.type`	字符串	错误类型（在某些情况下为错误代码）。

网络错误

网络错误包含有关失败 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`）。

操作时间属性

属性	类型	描述
`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 调用中给定的操作名称。

挫败信号（Frustration Signals）

FlashCat 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 检测到的错误点击（点击后触发错误）。

UTM 属性

如果 URL 中包含 UTM 参数,FlashCat 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 中追踪用户搜索以触发给定活动的关键字的参数。

数据存储

在上传到 FlashCat 之前,数据会以明文形式临时存储在浏览器的本地存储（LocalStorage 或 SessionStorage）中。SDK 会遵循以下规则：

当网络可用时,数据会以批次形式发送。

如果网络不可用或数据上传失败,批次会被保留直到成功发送。

超过一定时限的数据会被自动清理,以避免占用过多存储空间。

这意味着即使用户在离线时使用您的应用,也不会丢失数据。

注意：敏感数据不应包含在 RUM 事件中,或者应在发送前通过 beforeSend 回调进行混淆或过滤。

数据上传

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

批处理机制

事件收集：SDK 将事件添加到内存中的批次缓冲区。

批次上传：当满足以下条件之一时,批次会被上传：

批次中的事件数量达到阈值

批次大小达到阈值

定期上传（例如每 10 秒）

页面卸载时（beforeunload 事件）

上传策略

Beacon API：优先使用 Beacon API 发送数据,以确保在页面卸载时数据不会丢失。

XHR/Fetch Fallback：如果 Beacon API 不可用,则使用 XMLHttpRequest 或 Fetch API。

失败重试：如果上传失败,批次会被保留在本地存储,直到成功发送。

数据压缩

上传前,FlashCat SDK 会对批次数据进行压缩,以减少网络流量和上传时间。

隐私和合规

FlashCat Web RUM SDK 设计时考虑了隐私和数据保护:

IP 地址匿名化：可以配置 SDK 对 IP 地址进行匿名化处理。

敏感数据过滤：使用 beforeSend 回调过滤或混淆敏感信息。

Cookie 和存储控制：可以配置是否使用 Cookie 和本地存储。

GDPR/CCPA 合规：支持用户隐私选择退出机制。

有关隐私配置的更多信息,请参阅高级配置。

概述#

默认属性#

通用核心属性#

设备#

操作系统#

浏览器#

地理位置#

全局用户属性#

事件特定属性#

会话属性#

视图时间指标#

视图属性#

资源时间指标#

资源属性#

GraphQL 属性#

长任务时间属性#

错误属性#

源错误#

网络错误#

操作时间属性#

操作属性#

挫败信号（Frustration Signals）#

UTM 属性#

数据存储#

数据上传#

批处理机制#

上传策略#

数据压缩#

隐私和合规#

更多信息#

概述