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

# Android SDK 接入

> 快速集成 Android RUM SDK，实时监控应用性能、错误和用户行为

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

<Note>
  **关于依赖和包名的说明**

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

## 接入步骤

<Steps>
  <Step title="添加 SDK 依赖">
    在您的应用模块的 `build.gradle` 文件中添加 Flashduty SDK 依赖：

    ```groovy build.gradle theme={null}
    dependencies {
        implementation "cloud.flashcat:dd-sdk-android-core:<latest-version>"
        implementation "cloud.flashcat:dd-sdk-android-rum:<latest-version>"
    }
    ```

    <Tip>
      请访问 [Maven Central
      版本页面](https://central.sonatype.com/artifact/cloud.flashcat/dd-sdk-android-core/versions)
      获取最新版本号。
    </Tip>
  </Step>

  <Step title="获取应用凭证">
    在 Flashduty 控制台的 [RUM 应用管理](https://console.flashcat.cloud/rum/apps)页面：

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

  <Step title="初始化 SDK">
    在您的 `Application` 类的 `onCreate()` 方法中初始化 SDK：

    ```kotlin Application.kt theme={null}
    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)
        }
    }
    ```

    <Note>
      **参数说明：**

      * `environmentName` - 环境名称（如 production、staging）
      * `appVariantName` - 应用变体名称，用于区分不同构建版本的数据
      * 更多配置选项请参阅 [高级配置](https://docs.flashcat.cloud/zh/flashduty/rum/android-advanced-configuration)
    </Note>
  </Step>

  <Step title="启用 RUM 功能">
    配置并启用 Android SDK 的 RUM 功能：

    ```kotlin Application.kt theme={null}
    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)
    ```

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

      * 用户交互事件
      * 长任务监控
      * Activity 视图追踪
    </Check>
  </Step>

  <Step title="配置网络追踪（可选）">
    配置网络拦截器以追踪 HTTP 请求和响应：

    **添加 OkHttp 依赖：**

    ```groovy build.gradle theme={null}
    dependencies {
        implementation "cloud.flashcat:dd-sdk-android-okhttp:<latest-version>"
    }
    ```

    **配置拦截器：**

    ```kotlin theme={null}
    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()
    ```

    <Check>
      使用 `DatadogInterceptor` 后，OkHttpClient
      处理的每个请求都会被自动记录为资源，相关信息（URL、方法、状态码、错误）会自动填充。
    </Check>

    <Note>
      * 只有在视图处于活动状态时发起的网络请求才会被追踪 -
        要追踪应用在后台时的请求，请参阅 [追踪后台事件](#追踪后台事件) -
        如果使用多个拦截器，请将 `DatadogInterceptor` 添加为第一个拦截器
    </Note>

    **追踪网络重定向或重试：**

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

    ```kotlin theme={null}
    val okHttpClient = OkHttpClient.Builder()
        .addNetworkInterceptor(DatadogInterceptor.Builder(tracedHostsWithHeaderType).build())
        .build()
    ```

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

    **过滤特定错误：**

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

    ```kotlin theme={null}
    val rumConfig = RumConfiguration.Builder(applicationId)
        .setErrorEventMapper { errorEvent ->
            if (errorEvent.shouldBeDiscarded()) {
                null
            } else {
                errorEvent
            }
        }
        .build()
    ```
  </Step>
</Steps>

## 高级配置

### 追踪后台事件

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

```kotlin theme={null}
val rumConfig = RumConfiguration.Builder(applicationId)
    .trackBackgroundEvents(true)
    .build()
```

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

### 离线数据处理

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

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

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

### 追踪本地资源访问

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

<Tabs>
  <Tab title="Assets 资源">
    ```kotlin theme={null}
    val inputStream = context.getAssetAsRumResource(fileName)
    ```
  </Tab>

  <Tab title="Raw 资源">
    ```kotlin theme={null}
    val inputStream = context.getRawResAsRumResource(id)
    ```
  </Tab>
</Tabs>

## WebView 集成

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

<Steps>
  <Step title="添加 WebView 依赖">
    ```groovy build.gradle theme={null}
    dependencies {
        implementation "cloud.flashcat:dd-sdk-android-webview:<latest-version>"
    }
    ```
  </Step>

  <Step title="启用 WebView 追踪">
    在您的 Activity 或 Fragment 中启用 WebView 追踪：

    ```kotlin theme={null}
    import com.datadog.android.webview.WebViewTracking

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

    <Note>
      **参数说明：**

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

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

## 验证接入

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

<Steps>
  <Step title="访问控制台">
    登录 Flashduty 控制台，进入对应的 RUM 应用，查看是否有数据上报。
  </Step>

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

  <Step title="查看日志">
    在 Logcat 中查看是否有向数据上报端点的网络请求。

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

## 混淆配置

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

```proguard proguard-rules.pro theme={null}
# Flashduty SDK (兼容 Datadog 协议)
-keep class com.datadog.android.** { *; }
-dontwarn com.datadog.android.**
```

## 下一步

<CardGroup cols={2}>
  <Card title="高级配置" icon="sliders" href="/zh/rum/sdk/android/advanced-config">
    深入配置 SDK 的高级功能，如自定义采样、用户标识、全局上下文等
  </Card>

  <Card title="数据收集" icon="database" href="/zh/rum/sdk/android/data-collection">
    了解 SDK 收集的数据类型和数据结构
  </Card>

  <Card title="分析看板" icon="chart-line" href="/zh/rum/analytics/native">
    查看和分析应用的性能、错误和用户行为数据
  </Card>

  <Card title="错误追踪" icon="bug" href="/zh/rum/error-tracking/overview">
    配置崩溃报告和异常追踪功能
  </Card>
</CardGroup>