Skip to main content
关于依赖和包名的说明Flashduty Android SDK 完全兼容 Datadog 开源协议,代码中的 import 语句使用 com.datadog.android.* 包名。您可以无缝复用 Datadog 生态的文档、示例和最佳实践,同时享受 Flashduty 平台的服务。
Android RUM SDK 提供丰富的高级配置选项,帮助您根据业务需求定制数据收集和上下文信息。
支持的配置场景:
  • 丰富用户会话 - 添加自定义视图、操作、资源和错误信息
  • 保护敏感数据 - 屏蔽个人身份信息等敏感数据
  • 关联用户会话 - 将用户会话与内部用户标识关联
  • 控制数据量 - 通过采样和事件过滤优化数据收集
  • 增强上下文 - 为数据添加自定义属性

丰富用户会话

自定义视图

当使用 ActivityViewTrackingStrategy 或 FragmentViewTrackingStrategy 时,RUM SDK 会自动追踪视图。您也可以在视图变为可见或可交互时手动发送自定义 RUM 视图。
参数说明:
  • viewKey (String) - 视图的唯一标识符,同一个 viewKey 用于调用 startView() 和 stopView()
  • viewName (String) - 视图的名称
  • attributes (Map<String, Any?>) - 附加到视图的属性(可选)

自定义操作

除了自动追踪的用户交互,您还可以追踪特定的自定义用户操作(如点击、滑动、点赞)。

自定义资源

除了自动追踪的资源,您还可以手动追踪特定的自定义资源(如网络请求、第三方库加载)。

自定义错误

要记录特定错误,当异常发生时通知 RUM SDK:
更多错误上报详情,请参阅 Android 异常上报。

自定义计时

除了 RUM SDK 默认的性能指标,您还可以使用 addTiming API 测量关键操作的耗时。计时是相对于当前 RUM 视图开始时间的偏移量。
设置计时后,可通过 @view.custom_timings.<timing_name> 访问,例如 @view.custom_timings.hero_image。

设置用户信息

RUM SDK 支持设置标准用户信息。
当前仅支持设置用户标准字段:id、name、email、anonymous_id;其他用户属性不支持。如有需求,可以在 context 字段进行配置。

事件和数据管理

清除所有数据

使用 clearAllData 清除当前存储在 SDK 中的所有未发送数据:

停止数据收集

使用 stopInstance 停止收集数据并清除所有本地数据:
调用 stopInstance() 后,SDK 将完全停止工作,需要重新初始化才能恢复数据收集。

控制事件批量上传

RUM SDK 会自动批量上传事件。您可以通过配置参数控制批量上传的行为:

设置远程日志阈值

您可以为远程记录的消息定义最低日志级别。低于该级别的日志不会发送到 Flashduty:
设置 Log.WARN 阈值后,只有 WARN、ERROR 级别的日志会被上传,DEBUG 和 INFO 级别的日志将被过滤。

追踪自定义全局属性

除了由 RUM SDK 自动捕获的默认属性外,您还可以向 RUM 事件添加额外的上下文信息,例如自定义属性。
自定义属性的用途:
  • 根据业务信息(如购物车状态、用户等级、广告活动)过滤和分组用户行为
  • 跟踪特定用户的浏览路径
  • 了解哪些用户受错误影响最大
  • 监控关键用户的性能表现

追踪用户会话

要识别用户会话,在初始化 SDK 后使用 setUserInfo API:
当前仅支持设置用户标准字段:id、name、email、anonymous_id;其他用户属性不支持。如有需求,可以在 context 字段进行配置。
参数说明:
  • id (String) - 唯一用户标识符
  • name (String) - 用户友好名称,默认在 RUM UI 中显示
  • email (String) - 用户电子邮件,若无名称则显示邮件
  • 以上属性均为可选,建议至少提供一个

追踪属性

全局属性会被附加到所有 RUM 事件中,用于添加通用的上下文信息。 添加全局属性:
删除全局属性:

追踪 Widgets

Widgets 不会自动追踪。要监控 Widget 的交互,需要手动调用 API。

初始化参数

在初始化 Flashduty Android SDK 时,您可以使用 Configuration.Builder 配置多种选项。

自动追踪视图

要自动追踪视图(Activities、Fragments),在初始化时使用 useViewTrackingStrategy:

自动追踪网络请求

要自动追踪 HTTP 网络请求,请参考 SDK 接入指南 中的 OkHttp 拦截器配置。

自动追踪 Apollo GraphQL 请求

如果您使用 Apollo GraphQL 客户端进行网络调用,可以启用自动追踪。
1

添加 Apollo 依赖

在应用的 build.gradle 文件中添加依赖:
build.gradle
请访问 Maven Central 版本页面 获取最新版本号。
2

配置 Apollo Client

Flashduty 追踪头将自动添加到您的 GraphQL 请求中,使其能够被追踪。
限制说明:
  • 仅支持 Apollo 版本 4
  • 仅追踪 query 和 mutation 类型的操作,不追踪 subscription 操作
启用 GraphQL Payload 发送(可选):

自动追踪长任务

在主线程上执行的长时间运行的操作可能会影响应用的视觉性能和响应性。SDK 可以自动检测并追踪长任务。
默认阈值为 100ms。您可以根据应用性能要求调整此阈值。

修改或丢弃 RUM 事件

要在批量处理之前修改 RUM 事件的某些属性,或完全丢弃某些事件,请在初始化时提供 EventMapper<T> 的实现。

可修改的事件属性

当实现 EventMapper<T> 接口时,每种事件类型只有部分属性可以修改:
如果从 EventMapper<T> 实现中返回 null,则事件将被丢弃,不会发送到 Flashduty。

示例:丢弃敏感错误

获取 RUM Session ID

检索 RUM Session ID 对于故障排查很有帮助。您可以将 Session ID 附加到支持请求、电子邮件或错误报告中,以便支持团队在 Flashduty 中找到用户会话。
您可以在运行时访问 RUM Session ID,而无需等待 sessionStarted 事件。

采样控制

默认情况下,RUM 会收集所有会话的数据。您可以通过 sessionSampleRate 参数设置采样率来减少收集的会话数量。
采样率范围:0.0 - 100.0
  • 100.0 - 收集所有会话(默认)
  • 50.0 - 收集 50% 的会话
  • 0.0 - 不收集任何会话
被采样丢弃的会话将不收集任何页面视图及其相关遥测数据。

远程配置:在控制台调整采样率

自 0.7.0 起,会话采样率可以在 Flashcat 控制台的「远程配置」页里调整,无需发布新版本 App。该能力默认关闭,初始化时打开:
生效规则:
  • SDK 在启动时和每个新会话开始时各向控制台请求一次配置,拿到的配置用于下一个会话的抽样;正在进行的会话不会被重新抽样。
  • 例外是采样率跨过 0(从 0 调到非 0,或从非 0 调到 0):当前会话会立即结束,下一个会话按新采样率抽样,这样紧急关停或重新开启不必等会话自然轮换。
  • 请求失败、超时或响应不可读时,SDK 继续使用当前值;从未拿到过配置时,使用 setSessionSampleRate 设置的初始化值。配置会缓存在本地,下次冷启动的第一个会话就能用上。
  • 配置请求只携带 client token、环境、应用版本和 SDK 版本,不包含任何用户数据,因此不受用户跟踪同意状态限制。
  • 私有化部署时,配置接口位于 RUM 上报地址旁的 /config 路径(例如上报地址是 https://host/api/v2/rum,配置接口就是 https://host/api/v2/rum/config)。使用 useCustomEndpoint 时,请确认网关放行了该路径。

在应用内覆盖抽样结果

如果需要保证某些用户的会话一定被采集(例如内部测试账号、正在排查问题的用户),可以通过 setBeforeSampling 在每次抽样前给出最终采样率。回调返回 null 表示沿用传入的值;返回值不在 0 到 100 之间或回调抛出异常时,同样沿用传入的值,不会影响采集。
对于已经在运行的应用,也可以随时调用 setForcedSession(),从当前会话起强制采集该用户的所有会话,直到进程结束:

读取控制台的自定义配置

控制台「远程配置」页中的「自定义配置」会原样下发到 SDK,可通过 getRemoteConfig() 读取。SDK 不会解释这些值,含义完全由应用自己定义;没有发布配置或远程配置未开启时返回 null。
自定义配置对所有安装了 SDK 的客户端可见,请勿放入密钥、Token 或个人敏感信息。

用户跟踪同意

为遵守 GDPR、CCPA 等隐私法规,RUM 允许在初始化时设置用户跟踪同意状态。

同意状态说明

如果初始化时使用 TrackingConsent.PENDING,SDK 将开始收集数据,但在同意状态更改为 GRANTED 之前不会发送。

更改同意状态

您可以通过 setTrackingConsent API 在初始化后更改同意状态:

最佳实践

  • 确保在适当的生命周期方法中调用 startView 和 stopView,避免视图重复追踪
  • 为每个视图使用唯一的 viewKey
  • 使用自定义资源追踪时,确保每个 startResource 都有对应的 stopResource 或 stopResourceWithError 调用
  • 避免追踪内部资源或过于频繁的请求
  • 修改事件时,只有表格中列出的属性可以修改,其他属性的修改将被忽略
  • 返回 null 可丢弃整个事件
  • 合理设置采样率和批量上传频率,平衡数据量与性能开销
  • 避免在事件回调中执行耗时操作

相关文档

SDK 接入

了解如何接入 Android SDK

数据收集

了解 SDK 收集的数据类型

兼容性

了解 SDK 兼容性要求