Android SDK 数据收集 - Flashduty Docs

Flashduty Android RUM SDK 默认自动收集所有 RUM 事件的多个指标和属性。您还可以通过 API 添加自定义属性以扩展默认数据集。

隐私合规与权限说明

Flashduty Android RUM SDK 仅为真实用户体验监控、错误定位、性能分析和网络请求分析收集必要的运行时信息。SDK 自身声明的 Android 权限如下：

权限	用途
`android.permission.INTERNET`	上传 RUM、Trace、Log 等观测数据
`android.permission.ACCESS_NETWORK_STATE`	获取网络连接状态，用于标记事件发生时的网络环境

SDK 自身不会声明或要求 READ_PHONE_STATE、ACCESS_FINE_LOCATION、ACCESS_COARSE_LOCATION 等敏感权限。

不采集的设备标识

Android RUM SDK 不会读取或上报以下设备唯一标识：

标识	是否采集	说明
Android ID / SSAID (`Settings.Secure.ANDROID_ID`)	否	SDK 不读取 Android ID
IMEI / MEID / 设备号	否	SDK 不调用 `getDeviceId()`、`getImei()`、`getMeid()`
设备序列号	否	SDK 不读取 `Build.SERIAL` 或 `Build.getSerial()`
OAID / 广告 ID	否	SDK 不读取 OAID、GAID 或其他广告标识
手机号码、通讯录、短信、相册	否	SDK 不访问这些系统数据

RUM 默认可生成一个匿名用户 ID，用于跨会话关联同一匿名用户。该 ID 是 SDK 随机生成的 UUID，并存储在应用本地数据目录中，不来自 Android ID、IMEI、OAID 或广告 ID。您可以在 RUM 配置中关闭匿名用户追踪。

会采集的系统上下文

SDK 会自动附加以下系统上下文，帮助排查性能、崩溃和网络问题：

数据类别	示例	用途
应用信息	应用包名、版本名称、构建版本号、环境、服务名	区分应用、版本和环境
设备信息	设备品牌、型号、设备类型、CPU 架构、屏幕数量	分析设备兼容性和性能差异
系统信息	Android 版本、系统主版本、系统构建号、语言、时区	定位系统版本或区域相关问题
网络信息	网络类型、蜂窝网络制式、运营商名称、上下行带宽、信号强度	分析网络质量对体验的影响
RUM 事件	View、Action、Resource、Error、Long Task、启动耗时	还原用户旅程、定位错误和性能瓶颈
用户信息	`usr.id`、`usr.name`、`usr.email` 及自定义属性	仅在业务主动调用 API 设置时附加

本文档列出的“地理位置”字段由 Flashduty 后端根据客户端请求 IP 推断，不是 Android 客户端读取系统定位。SDK 不调用 GPS、基站定位或融合定位 API，也不需要定位权限。

应用启动指标

Flashduty 自动收集以下应用启动性能指标：

指标	描述	测量范围
cold_start_duration	冷启动持续时间	从应用进程创建到首个 Activity 渲染完成
warm_start_duration	温启动持续时间	应用进程已存在，从 Activity 开始到渲染完成
hot_start_duration	热启动持续时间	应用和 Activity 都在内存中，从恢复到渲染完成
activity_start_duration	Activity 启动持续时间	从 `onCreate` 到首帧绘制完成
is_pre_warmed	预热启动标识	布尔值，指示应用是否通过预热启动（Android 11+）

启动类型说明：

冷启动 - 应用首次启动或进程被终止后启动，需要加载所有资源并初始化应用状态
温启动 - 应用进程在内存中，但 Activity 需要重新创建
热启动 - 应用和 Activity 都在内存中，只需将 Activity 带回前台

Views 监控

View 代表用户在应用中看到的唯一屏幕。每个 View 开始时会创建一个新的 RUM 事件，并在 View 的整个生命周期内更新该事件。

View 会收集其生命周期内发生的所有资源、操作、错误和长任务的相关信息。

自动追踪策略

在 Android 中，Activities 和 Fragments 被视为 View。SDK 提供以下自动追踪策略：

策略	描述	适用场景
ActivityViewTrackingStrategy	基于 Activity 生命周期追踪	传统 Activity 架构
FragmentViewTrackingStrategy	基于 Fragment 生命周期追踪	Fragment 为主的应用
MixedViewTrackingStrategy	同时追踪 Activity 和 Fragment	混合架构应用
NavigationViewTrackingStrategy	适用于 Jetpack Navigation 组件	使用 Navigation 的应用

您也可以通过手动调用 RumMonitor.startView() 和 RumMonitor.stopView() 来自定义 View 追踪。

默认属性

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

通用核心属性

属性名	类型	描述
`application.id`	string	Flashduty 应用 ID。
`application.name`	string	应用包名(例如 `com.example.app`)。
`application.version`	string	应用版本名称。
`application.build`	string	应用构建版本号。
`session.id`	string	唯一会话 ID,用于将用户旅程中的事件分组。
`session.type`	string	会话类型:`user`。
`view.id`	string	为每个 View 生成的唯一 ID。
`view.url`	string	View 的规范化 URL(Activity 或 Fragment 的类名)。
`view.name`	string	可自定义的 View 名称。
`env`	string	应用的环境名称(例如 `prod`、`dev`)。
`service`	string	服务名称,用于区分应用的不同模块或微服务。
`version`	string	应用版本。
`sdk_version`	string	Flashduty SDK 版本。
`date`	number	事件发生的时间戳（epoch 毫秒）
`type`	string	事件类型（如 `view`、`resource`、`action`、`error`、`long_task`）

设备属性

以下属性与设备相关，在所有 RUM 事件中自动收集：

属性名	类型	描述
`device.type`	string	设备类型,如 `mobile`、`tablet`、`tv` 等。
`device.name`	string	设备商业名称(例如 `Samsung Galaxy S21`)。
`device.model`	string	设备型号(例如 `SM-G991B`)。
`device.brand`	string	设备品牌(例如 `Samsung`)。
`device.architecture`	string	设备架构（例如 `arm64-v8a`）
`device.marketing_name`	string	设备的市场营销名称

连接性属性

以下网络相关属性在所有 RUM 事件中自动收集：

属性名	类型	描述
`connectivity.status`	string	设备网络可达性状态(`connected`、`not_connected`、`maybe`)。
`connectivity.interfaces`	array	可用网络接口列表(例如 `wifi`、`cellular`、`ethernet`)。
`connectivity.cellular.technology`	string	蜂窝网络技术类型（例如 `LTE`、`5G`）
`connectivity.cellular.carrier_name`	string	运营商名称（例如 `中国移动`）

操作系统属性

以下操作系统相关属性在所有 RUM 事件中自动收集：

属性名	类型	描述
`os.name`	string	操作系统名称(例如 `Android`)。
`os.version`	string	操作系统版本(例如 `13`)。
`os.version_major`	string	操作系统主版本号（例如 `13`）
`os.build`	string	系统构建号（例如 `TQ2A.230505.002`）

地理位置属性

RUM 可以从用户的 IP 地址推断出地理位置信息：

属性名	类型	描述
`geo.country`	string	国家名称
`geo.country_iso`	string	国家的 ISO 代码
`geo.city`	string	城市名称

地理位置信息由 Flashduty 后端根据客户端 IP 地址推断，不会在 Android 客户端收集精确的 GPS 位置，也不需要定位权限。

全局用户属性

您可以通过 setUser() API 设置用户信息，这些信息会被附加到所有 RUM 事件中：

属性名	类型	描述
`usr.id`	string	用户的唯一标识符
`usr.name`	string	用户的友好名称
`usr.email`	string	用户的电子邮件地址

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

事件特定属性

除了默认属性外，不同类型的 RUM 事件还会收集特定的指标和属性。

Session 属性

属性名	类型	描述
`session.id`	string	唯一会话 ID。
`session.type`	string	会话类型:`user`。
`session.has_replay`	bool	会话是否包含会话重放录制
`session.is_active`	bool	会话是否处于活动状态

View 属性

View 事件包含以下特定属性和性能指标：

属性名	类型	描述
`view.id`	string	每个 View 的唯一 ID。
`view.name`	string	View 的自定义名称。
`view.url`	string	View 的 URL(Activity 或 Fragment 类名)。
`view.time_spent`	number(ns)	用户在此 View 上花费的时间。
`view.loading_time`	number(ns)	View 加载完成所需的时间。
`view.loading_type`	string	View 加载类型:`initial_load`、`activity_display`、`fragment_display`。
`view.first_contentful_paint`	number(ns)	首次内容绘制时间(仅适用于 API 29+)。
`view.action.count`	number	View 中收集的所有操作的数量。
`view.resource.count`	number	View 中收集的所有资源的数量。
`view.error.count`	number	View 中收集的所有错误的数量。
`view.long_task.count`	number	View 中收集的所有长任务的数量。
`view.crash.count`	number	View 中收集的所有崩溃的数量
`view.is_active`	bool	View 是否仍处于活动状态

Resource 属性

Resource 事件表示应用中的网络请求。收集的属性包括：

属性名	类型	描述
`resource.id`	string	资源的唯一标识符。
`resource.type`	string	资源类型(例如 `xhr`、`fetch`、`image`、`css`、`js`、`font`、`media`、`other`)。
`resource.url`	string	资源的 URL。
`resource.method`	string	HTTP 方法(例如 `GET`、`POST`)。
`resource.status_code`	number	HTTP 响应状态码。
`resource.duration`	number(ns)	加载资源所花费的总时间。
`resource.size`	number	资源大小(字节)。
`resource.dns.duration`	number(ns)	DNS 解析时间(`domainLookupEnd - domainLookupStart`)。
`resource.connect.duration`	number(ns)	建立连接的时间(`connectEnd - connectStart`)。
`resource.ssl.duration`	number(ns)	TLS 握手时间(`connectEnd - secureConnectionStart`),仅适用于 HTTPS。
`resource.first_byte.duration`	number(ns)	等待首字节响应的时间(`responseStart - requestStart`)。
`resource.download.duration`	number(ns)	下载响应的时间(`responseEnd - responseStart`)。
`resource.redirect.duration`	number(ns)	后续 HTTP 重定向所花费的时间(`redirectEnd - redirectStart`)。
`resource.provider.name`	string	资源提供商名称,默认为 `unknown`。
`resource.provider.domain`	string	资源提供商域名
`resource.provider.type`	string	资源提供商类型（如 `first-party`、`cdn`、`ad`、`analytics`）

Error 属性

错误事件收集异常和崩溃信息，错误消息和堆栈跟踪会被自动包含：

属性名	类型	描述
`error.source`	string	错误来源(例如 `webview`、`logger`、`network`、`source`、`console`)。
`error.type`	string	错误类型或错误代码。
`error.message`	string	简洁、人类可读的单行错误消息。
`error.stack`	string	堆栈跟踪或错误的补充信息。
`error.issue_id`	string	错误问题的唯一标识符。
`error.category`	string	错误的高级分类,可能的值:`ANR`(应用无响应)、`Exception`(异常)。
`error.file`	string	发生错误的文件名(用于错误追踪问题)。
`error.line`	number	发生错误的行号
`error.is_crash`	bool	指示该错误是否导致应用崩溃

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

属性名	类型	描述
`error.resource.status_code`	number	HTTP 响应状态码。
`error.resource.method`	string	HTTP 方法(例如 `POST`、`GET`)。
`error.resource.url`	string	资源 URL。
`error.resource.provider.name`	string	资源提供商名称,默认为 `unknown`。
`error.resource.provider.domain`	string	资源提供商域名
`error.resource.provider.type`	string	资源提供商类型（如 `first-party`、`cdn`、`ad`、`analytics`）

Action 属性

Action 代表用户与应用的交互（例如点击、滑动、滚动）。计时属性：

属性名	类型	描述
`action.loading_time`	number(ns)	操作的加载时间。
`action.long_task.count`	number	此操作收集的所有长任务数量。
`action.resource.count`	number	此操作收集的所有资源数量
`action.error.count`	number	此操作收集的所有错误数量

基本属性：

属性名	类型	描述
`action.id`	string	用户操作的 UUID
`action.type`	string	用户操作类型（如 `tap`、`scroll`、`swipe`、`application_start`）
`action.name`	string	用户操作的名称
`action.target.name`	string	用户交互的元素，仅适用于自动收集的操作

数据存储与安全

本地存储机制

在数据上传到 Flashduty 之前，会以明文形式存储在应用的缓存目录中。 存储位置：

/data/data/<package_name>/cache/com.flashcat.rum/

安全保护：

缓存文件夹受 Android 应用沙箱保护
在大多数设备上，其他应用无法读取这些数据

安全注意事项：

如果移动设备已 root 或有人篡改 Linux 内核，存储的数据可能会变得可读
敏感数据不应包含在 RUM 事件中，或者应在发送前通过 EventMapper 进行混淆或过滤

数据上传机制

Android RUM SDK 采用批处理方式上传事件，在保证数据传输的同时最小化对用户体验的影响。

批处理流程

事件收集

SDK 将未压缩的事件追加到批次文件中，使用 TLV 编码格式（Tag-Length-Value）。

批次优化

当批次关闭时：

读取批次文件并提取事件
对 RUM 事件进行去重优化（删除冗余的 View 事件）
构建特定于每个追踪的有效载荷

压缩上传

使用 gzip 压缩数据，减少网络流量和上传时间。

上传触发条件

批次在以下任一情况下会被上传：

触发条件	说明
文件大小	批次文件大小达到阈值（例如 4MB）
事件数量	批次中的事件数量达到阈值
应用状态	应用切换到后台
定时上传	定期上传（例如每 5 秒）

上传策略

智能上传机制：

网络优化 - 优先通过 WiFi 上传，移动网络也支持
电量管理 - 确保不会过度消耗设备电量
失败重试 - 上传失败时批次会保留在本地，直到成功发送
数据压缩 - 使用 gzip 压缩，减少网络流量

Direct Boot 模式支持

如果您的应用支持 Direct Boot 模式（在设备解锁前启动），请注意：

在设备解锁前捕获的数据将不会被记录，因为此时凭据加密存储尚不可用。

Flashduty SDK 会在设备解锁后开始收集数据。如果您需要在 Direct Boot 模式下收集数据，请确保使用设备加密存储而非凭据加密存储。

SDK 接入

了解如何集成 Android SDK

高级配置

配置自定义属性、采样和事件过滤

兼容性

了解 SDK 兼容性要求

​隐私合规与权限说明

​不采集的设备标识

​会采集的系统上下文

​应用启动指标

​Views 监控

​自动追踪策略

​默认属性

​事件特定属性

​数据存储与安全

​本地存储机制

​数据上传机制

​批处理流程

​上传触发条件

​上传策略

​Direct Boot 模式支持

​相关文档

SDK 接入

高级配置

兼容性

隐私合规与权限说明

不采集的设备标识

会采集的系统上下文

应用启动指标

Views 监控

自动追踪策略

默认属性

事件特定属性

数据存储与安全

本地存储机制

数据上传机制

批处理流程

上传触发条件

上传策略

Direct Boot 模式支持

相关文档