Android SDK 接入 - Flashduty Docs

Flashduty Android RUM SDK 支持 Android 6.0 (API level 23) 及以上版本。通过集成 SDK，您可以实时监控 Android 应用的性能、错误和用户行为。

关于依赖和包名的说明Flashduty Android SDK 完全兼容 Datadog 开源协议，代码中的 import 语句使用 com.datadog.android.* 包名。您可以无缝复用 Datadog 生态的文档、示例和最佳实践，同时享受 Flashduty 平台的服务。

接入步骤

添加 SDK 依赖

在您的应用模块的 build.gradle 文件中添加 Flashduty SDK 依赖：

build.gradle

dependencies {
    implementation "cloud.flashcat:dd-sdk-android-core:<latest-version>"
    implementation "cloud.flashcat:dd-sdk-android-rum:<latest-version>"

    // 必需：SDK 运行时依赖 Gson 与 OkHttp，需由宿主应用提供
    implementation "com.google.code.gson:gson:2.8.9"
    implementation "com.squareup.okhttp3:okhttp:4.9.0"

    // 可选：如需后台上传能力，请按项目兼容版本引入 WorkManager
    implementation "androidx.work:work-runtime:<workmanager-version>"
}

请访问 Maven Central 版本页面获取最新版本号。

Gson 与 OkHttp 必须由您的应用显式声明。 SDK 通过反射检测这两个依赖是否存在，但它们在 SDK 内部是 compileOnly 依赖、不会随 SDK 传递到您的工程。如果缺失，Datadog.initialize(...) 会抛出 missing dependencies 异常并导致应用启动崩溃（即使未开启混淆）。若您的应用已经引入了 Gson / OkHttp，可直接复用，无需重复添加。

WorkManager 也是 SDK 的 compileOnly 依赖，但不是强制依赖。缺少 WorkManager 时，SDK 会记录告警并禁用后台上传能力；前台批量上报仍可继续工作。若您希望 SDK 在应用进入后台后继续调度上传任务，请在应用中显式引入 androidx.work:work-runtime。

获取应用凭证

在 Flashduty 控制台的 RUM 应用管理页面：

创建或选择一个 Android 应用
获取以下凭证信息：
- Application ID - 应用唯一标识符
- Client Token - 客户端访问令牌

初始化 SDK

在您的 Application 类的 onCreate() 方法中初始化 SDK：

Application.kt

import com.datadog.android.Datadog
import com.datadog.android.core.configuration.Configuration
import com.datadog.android.privacy.TrackingConsent

class SampleApplication : Application() {
    override fun onCreate() {
        super.onCreate()

        val clientToken = "<CLIENT_TOKEN>"
        val environmentName = "<ENV_NAME>"
        val appVariantName = "<APP_VARIANT_NAME>"

        val configuration = Configuration.Builder(
            clientToken = clientToken,
            env = environmentName,
            variant = appVariantName
        ).build()

        Datadog.initialize(this, configuration, TrackingConsent.GRANTED)
    }
}

参数说明：

environmentName - 环境名称（如 production、staging）
appVariantName - 应用变体名称，用于区分不同构建版本的数据
更多配置选项请参阅高级配置

启用 RUM 功能

配置并启用 Android SDK 的 RUM 功能：

Application.kt

import com.datadog.android.rum.Rum
import com.datadog.android.rum.RumConfiguration
import com.datadog.android.rum.tracking.ActivityViewTrackingStrategy

val rumConfig = RumConfiguration.Builder(applicationId)
    .trackUserInteractions()
    .trackLongTasks(durationThreshold)
    .useViewTrackingStrategy(ActivityViewTrackingStrategy(true))
    .build()

Rum.enable(rumConfig)

SDK 将自动开始收集以下数据：

用户交互事件
长任务监控
Activity 视图追踪

配置网络追踪（可选）

配置网络拦截器以追踪 HTTP 请求和响应：

开启分布式 Trace 追踪

如果只需要在 RUM 中查看请求 URL、方法、状态码和错误，配置 OkHttp 拦截器即可。若需要把移动端请求与后端 Trace 链路关联，还需要额外引入 Trace 模块并启用 Trace.enable(...)。

添加 OkHttp 依赖：

build.gradle

dependencies {
    implementation "cloud.flashcat:dd-sdk-android-okhttp:<latest-version>"
    implementation "cloud.flashcat:dd-sdk-android-trace:<latest-version>"
}

dd-sdk-android-okhttp 负责把 OkHttp 请求记录为 RUM Resource；dd-sdk-android-trace 负责开启 Trace 功能、创建 span 并向一方域名请求注入 trace header。依赖使用 cloud.flashcat，代码 import 仍使用 com.datadog.android.* 包名。启用 Trace 功能：在 Datadog.initialize(...) 之后、发起网络请求之前启用 Trace：

Application.kt

import com.datadog.android.trace.DatadogTracing
import com.datadog.android.trace.GlobalDatadogTracer
import com.datadog.android.trace.Trace
import com.datadog.android.trace.TraceConfiguration

Trace.enable(
    TraceConfiguration.Builder().build()
)

GlobalDatadogTracer.registerIfAbsent(
    DatadogTracing.newTracerBuilder()
        .withServiceName("<SERVICE_NAME>")
        .build()
)

Trace.enable(...) 是开启 Trace feature 的必要步骤。GlobalDatadogTracer 用于注册全局 tracer，方便 OkHttp、协程和手动 span 复用同一套 trace 配置；如果只使用 OkHttp 自动追踪，SDK 会在未注册全局 tracer 时创建本地 tracer，但建议显式注册以便指定 service 名称并降低排查成本。

配置拦截器：

import com.datadog.android.okhttp.DatadogInterceptor
import com.datadog.android.trace.TracingHeaderType

val tracedHostsWithHeaderType = mapOf(
    "example.com" to setOf(
        TracingHeaderType.DATADOG, // datadog 协议
        TracingHeaderType.TRACECONTEXT // w3c 标准协议
    ),
    "api.example.com" to setOf(
        TracingHeaderType.DATADOG,
        TracingHeaderType.TRACECONTEXT
    )
)

val okHttpClient = OkHttpClient.Builder()
    .addInterceptor(DatadogInterceptor.Builder(tracedHostsWithHeaderType).build())
    .build()

使用 DatadogInterceptor 后，OkHttpClient 处理的一方域名请求会被自动记录为 RUM Resource，并在命中采样时注入 x-datadog-* 和 traceparent / tracestate 等 trace header，用于关联后端 Trace。

host 只填写域名，不要包含 http://、https:// 或路径；配置 example.com 会匹配 api.example.com 等子域名
只有在视图处于活动状态时发起的网络请求才会被追踪；要追踪应用在后台时的请求，请参阅追踪后台事件
如果使用多个拦截器，请将 DatadogInterceptor 添加为第一个拦截器；后续拦截器重新构造 Request 时需保留已有 headers

追踪网络重定向或重试：要监控网络重定向或重试，可以将 DatadogInterceptor 用作网络拦截器：

val okHttpClient = OkHttpClient.Builder()
    .addNetworkInterceptor(DatadogInterceptor.Builder(tracedHostsWithHeaderType).build())
    .build()

您还可以为 OkHttpClient 添加 EventListener，以自动追踪第三方提供商和网络请求的资源时序。

过滤特定错误：要过滤 DatadogInterceptor 报告的特定错误，可以在 RumConfiguration 中配置自定义 EventMapper：

val rumConfig = RumConfiguration.Builder(applicationId)
    .setErrorEventMapper { errorEvent ->
        if (errorEvent.shouldBeDiscarded()) {
            null
        } else {
            errorEvent
        }
    }
    .build()

高级配置

追踪后台事件

您可以追踪应用在后台运行时的事件（例如崩溃和网络请求）：

val rumConfig = RumConfiguration.Builder(applicationId)
    .trackBackgroundEvents(true)
    .build()

追踪后台事件可能会产生额外的会话，从而影响计费。如有疑问，请联系 Flashduty 支持团队。

离线数据处理

Android SDK 确保在用户设备离线时的数据可用性：

数据持久化机制： - 网络信号弱或设备电量过低时，事件以批次形式存储在本地 - 网络恢复后自动上传，确保不丢失数据 - 自动清理过旧数据，避免占用过多磁盘空间

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

追踪本地资源访问

您可以追踪 assets 和 raw 资源的访问情况：

Assets 资源
Raw 资源

val inputStream = context.getAssetAsRumResource(fileName)

val inputStream = context.getRawResAsRumResource(id)

WebView 集成

如果您的 Android 应用中包含 WebView，可以启用 WebView 追踪来监控 Web 内容的性能和错误。

添加 WebView 依赖

build.gradle

dependencies {
    implementation "cloud.flashcat:dd-sdk-android-webview:<latest-version>"
}

启用 WebView 追踪

在您的 Activity 或 Fragment 中启用 WebView 追踪：

import com.datadog.android.webview.WebViewTracking

// 为指定的 WebView 启用追踪
WebViewTracking.enable(webView, listOf("example.com", "*.example.com"))

参数说明：

webView - 需要追踪的 WebView 实例
allowedHosts - 允许追踪的域名列表，支持通配符（如 *.example.com）

WebView 中的 Web 页面现在可以与原生应用的 RUM 数据关联起来。

验证接入

接入完成后，验证集成是否成功：

访问控制台

触发测试事件

在应用中执行以下操作验证数据采集： - 打开应用的不同页面，验证页面浏览事件 - 执行用户操作（点击、滑动等），验证交互事件 - 触发网络请求，验证资源加载事件

查看日志

在 Logcat 中查看是否有向数据上报端点的网络请求。

如果看到数据上报请求且控制台中有数据显示，说明集成成功！

混淆配置

如果您的应用启用了代码混淆（ProGuard/R8），请在 proguard-rules.pro 文件中添加以下规则：

proguard-rules.pro

# Flashduty SDK (兼容 Datadog 协议)
-keep class com.datadog.android.** { *; }
-dontwarn com.datadog.android.**

自 0.4.1 起，SDK 已通过 AAR consumer rules 内置自身所需的混淆规则，包括保留 SourceFile、LineNumberTable、SDK shaded 依赖，以及初始化时通过反射检测的 Gson / OkHttp 关键类。您无需为 SDK 手动添加 Gson / OkHttp keep 规则。上述规则仅用于保留 SDK 公开类。如果您自己使用 Gson 序列化业务模型，仍需按 Gson 惯例为您自己的 model 类添加 keep 规则。

下一步

高级配置

深入配置 SDK 的高级功能，如自定义采样、用户标识、全局上下文等

数据收集

了解 SDK 收集的数据类型和数据结构

分析看板

查看和分析应用的性能、错误和用户行为数据

错误追踪

配置崩溃报告和异常追踪功能

​接入步骤

​开启分布式 Trace 追踪

​高级配置

​追踪后台事件

​离线数据处理

​追踪本地资源访问

​WebView 集成

​验证接入

​混淆配置

​下一步

高级配置

数据收集

分析看板

错误追踪

接入步骤

开启分布式 Trace 追踪

高级配置

追踪后台事件

离线数据处理

追踪本地资源访问

WebView 集成

验证接入

混淆配置

下一步