第3章：Android SDK集成——添加依赖、初始化、启用性能监控、验证SDK状态

3.1 集成原理概述

Firebase Performance SDK 通过 Gradle 插件在编译期自动注入字节码插桩，采集应用主线程耗时、网络请求、屏幕渲染等指标。SDK 集成包含四个关键阶段：

• 依赖声明：在 build.gradle 中添加 Firebase Performance 插件与库依赖。
• Firebase 初始化：通过 google-services.json 或手动调用 FirebaseApp.initializeApp() 建立后端连接。
• 启用性能监控：默认初始化即自动启用，但可通过 PerformanceConfiguration 控制采集开关与采样率。
• 状态验证：通过日志过滤器、Android Studio Profiler 或 Firebase 控制台确认 SDK 是否正常上报。

3.2 完整的集成流程

以下步骤从零开始，在 Android 项目中将 Firebase Performance SDK 接入到位。所有操作基于 AGP 8.x 与 Firebase BoM 32.x 版本。

3.2.1 添加 Gradle 依赖

在项目级 build.gradle.kts（或 build.gradle）中声明 Firebase Performance 插件：

// 项目级 build.gradle.kts
plugins {
    id("com.android.application") version "8.2.0" apply false
    // 添加 Firebase Perf 插件
    id("com.google.firebase.firebase-perf") version "1.4.2" apply false
}

在模块级 build.gradle.kts 中应用插件并添加库依赖：

// 模块级 build.gradle.kts
plugins {
    id("com.android.application")
    id("com.google.gms.google-services")    // Google Services 插件
    id("com.google.firebase.firebase-perf") // Performance 插件
}

dependencies {
    // Firebase BoM — 统一管理版本
    implementation(platform("com.google.firebase:firebase-bom:32.7.0"))
    // Performance 监控库
    implementation("com.google.firebase:firebase-perf")
    // 可选：Crashlytics 联动（用于卡顿堆栈分析）
    implementation("com.google.firebase:firebase-crashlytics")
}

3.2.2 放置 google-services.json

从 Firebase 控制台创建 Android 应用后下载 google-services.json，将其复制到 app/ 根目录下。Google Services 插件会在构建时解析该文件，自动完成 Firebase 初始化配置。

如果无法使用 google-services.json，也可在 AndroidManifest.xml 中手动配置应用 ID：

<meta-data
    android:name="com.google.firebase.perf.ApplicationId"
    android:value="1:123456789:android:abcdef123456" />

3.2.3 初始化 SDK（默认自动）

Firebase Performance SDK 在应用启动时通过 FirebaseInitProvider 自动初始化，无需手动调用。初始化后会立即开始采集屏幕渲染与网络请求数据。

如需手动控制初始化时机（例如推迟到关键业务加载后），可在 AndroidManifest.xml 中禁用自动初始化：

<provider
    android:name="com.google.firebase.perf.provider.FirebasePerfProvider"
    android:authorities="${applicationId}.firebaseperfprovider"
    android:exported="false"
    android:initOrder="101"
    tools:node="remove" />

然后在代码中手动初始化：

// 手动初始化 Performance SDK
FirebasePerformance.getInstance().setPerformanceCollectionEnabled(true);

3.2.4 启用/禁用性能监控

默认情况下，SDK 初始化后即启用采集。可通过运行时配置动态控制：

// 启用性能监控
FirebasePerformance.getInstance().setPerformanceCollectionEnabled(true);

// 禁用性能监控
FirebasePerformance.getInstance().setPerformanceCollectionEnabled(false);

3.3 验证 SDK 状态

集成完成后，必须验证 SDK 是否正常工作。以下是三种验证方法：

使用 Logcat 过滤验证的典型输出：

// 成功初始化日志
D/FirebasePerformance: FirebasePerformance is enabled.
D/FirebasePerformance: Initializing Firebase Performance SDK
D/FirebasePerformance: Screen trace monitoring is enabled.

// 采集到 HTTP 请求的日志
D/FirebasePerformance: Network request recorded: https://api.example.com/data 200 342ms

如果日志中未出现 FirebasePerformance is enabled，请检查 google-services.json 是否放置正确，以及插件是否在 Gradle 中成功应用。

3.4 SDK 集成全流程结构图

下图概括了从 Gradle 配置到验证 SDK 状态的完整集成链路，包含关键节点与决策分支：

3.5 常见错误与排障

3.6 性能与稳定性优化建议

• 按需启用采集：在调试或灰度阶段禁用全量采集，仅在需要分析的场景动态启用 setPerformanceCollectionEnabled(true)，减少不必要的性能开销。
• 控制采样率：通过 PerformanceConfiguration 设置采样比例，避免高并发场景下 SDK 自身采集成为瓶颈。
• 延迟初始化：如果应用启动阶段有大量初始化逻辑，可推迟 SDK 初始化到首屏渲染完成后，防止字节码插桩影响启动耗时。
• 版本对齐：始终使用 Firebase BoM 管理版本，避免因版本不匹配导致采集异常或内存泄漏。