Firebase App Distribution Android 快速入门：实现应用内新版本构建提醒

• 示例工程

Firebase App Distribution 的 Android SDK 可以让测试人员在 App 内直接收到新版本构建可安装的提醒（in-app alert），无需反复刷新邮箱或后台。本文基于 quickstart-android 仓库中的appdistribution示例模块，从依赖接入、初始化到核心 APIupdateIfNewReleaseAvailable()的完整调用链路，讲解如何快速为 Android 应用接入并定制测试版新版本提醒，并给出 Java 与 Kotlin 双版本实现、构建配置要点及常见问题排查思路。

图片说明：以下是 App Distribution Quickstart 应用运行后的真实界面，弹窗即 SDK 展示的"Enable new build alerts"新构建提醒交互。

1. App Distribution SDK 是什么

Firebase App Distribution 是一个面向测试分发的服务：开发者通过 Firebase 控制台或 CLI 上传 APK / AAB，测试人员在手机上安装后即可持续收到新版本推送。而 Android 端的 App Distribution SDK 将"提醒"这件事做到了应用内部——当你的应用启动或回到前台时，SDK 会查询是否有新版本可用，如果有，就在应用内弹出提示，引导测试人员直接下载安装，整个流程不依赖外部通知渠道。

仓库 appdistribution/README.md 对该示例的定位表述得非常清楚：展示如何使用 App Distribution SDK 来创建和定制面向测试人员的新构建提醒（new build alerts）。本模块正是围绕这一核心能力展开的最小可运行示例。

2. 示例工程结构

在仓库中，appdistribution是一个独立的 Gradle 工程，内部结构如下：

appdistribution/ ├── app/ │ ├── build.gradle.kts # 模块构建脚本（依赖、SDK 配置） │ └── src/ │ ├── androidTest/ # 设备端仪器测试 │ └── main/ │ ├── AndroidManifest.xml │ ├── java/com/google/firebase/appdistributionquickstart/ │ │ ├── EntryChoiceActivity.kt # 入口选择页（Java / Kotlin） │ │ ├── java/MainActivity.java # Java 版本示例 │ │ └── kotlin/KotlinMainActivity.kt # Kotlin 版本示例 │ └── res/ # 布局、字符串、图标等资源 ├── docs/result.png # 运行结果截图 ├── settings.gradle.kts # 工程与子模块声明 └── gradlew / gradlew.bat # Gradle 包装脚本

该工程在根目录 settings.gradle.kts 中被注册为:appdistribution:app模块，与:auth:app、:firestore:app等其他 Firebase 示例并列，说明它遵循整个仓库统一的构建体系。

应用提供了两个入口 Activity（分别对应 Java 与 Kotlin 两种实现），并由EntryChoiceActivity作为 Launcher 统一选择进入，见 AndroidManifest.xml。这种"同一功能、双语言演示"的组织方式，是 quickstart 系列仓库的典型做法，方便开发者对照学习。

3. 依赖接入：使用 Firebase BoM 管理版本

接入 App Distribution SDK 的第一步是在模块构建脚本中添加依赖。示例模块 appdistribution/app/build.gradle.kts 给出了完整做法：

plugins { id("com.android.application") id("com.google.gms.google-services") } dependencies { // 导入 Firebase BoM，统一管理 Firebase 各库版本 implementation(platform("com.google.firebase:firebase-bom:34.18.0")) // 引入 App Distribution SDK（示例使用的是 prerelease beta 版本） implementation("com.google.firebase:firebase-appdistribution:16.0.0-beta20") // 官方推荐配合 Google Analytics，以获得最优体验（非必需） implementation("com.google.firebase:firebase-analytics") }

几个值得注意的要点：

• Firebase BoM（Bill of Materials）：通过platform("com.google.firebase:firebase-bom:34.18.0")引入后，后续所有 Firebase 依赖都无需显式声明版本号，BoM 会统一对齐兼容版本。仓库的版本目录 gradle/libs.versions.toml 中定义firebaseBom = "34.18.0"，与示例中的写法保持一致。
• SDK 版本：示例当前锁定的是16.0.0-beta20，属于 prerelease 变体（构建脚本注释也写明 "ADD the SDK to the 'prerelease' variant only"）。生产环境请以官方文档发布的稳定版本为准。
• Google Analytics 可选：firebase-analytics并非 SDK 运行的必要条件，但官方推荐添加，因为它能为测试分发提供更完整的漏斗与行为数据。
• com.google.gms.google-services插件：用于读取google-services.json完成 Firebase 初始化，这是所有 Firebase Android 集成的前提。

此外模块还启用了viewBinding = true（build.gradle.kts），因此源码中可以直接使用ActivityMainBinding访问布局视图。

4. 核心 API：updateIfNewReleaseAvailable()

SDK 的核心入口是FirebaseAppDistribution单例对象，其关键方法是updateIfNewReleaseAvailable()。该方法会异步检查是否有新版本构建可供测试人员安装；如果存在新版本，SDK 会自动弹出一个应用内提醒对话框，供测试人员点击"Turn On"开启提醒并进入下载安装流程。

4.1 Kotlin 版本

见 KotlinMainActivity.kt：

import com.google.firebase.appdistribution.FirebaseAppDistribution import com.google.firebase.appdistribution.FirebaseAppDistributionException import com.google.firebase.appdistribution.appDistribution import com.google.firebase.Firebase class KotlinMainActivity : AppCompatActivity() { private lateinit var firebaseAppDistribution: FirebaseAppDistribution override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) val binding = ActivityMainBinding.inflate(layoutInflater) setContentView(binding.root) // 获取 FirebaseAppDistribution 单例（Kotlin 扩展属性写法） firebaseAppDistribution = Firebase.appDistribution } override fun onResume() { super.onResume() // 每次回到前台时检查新版本 firebaseAppDistribution.updateIfNewReleaseAvailable() .addOnProgressListener { updateProgress -> // （可选）在系统 NotificationManager 的自动更新之外， // 实现自定义的进度更新 } .addOnFailureListener { e -> if (e is FirebaseAppDistributionException) { // 处理异常 } } } }

4.2 Java 版本

对应的 Java 实现见 MainActivity.java，逻辑完全一致，仅在语法上不同：

import com.google.firebase.appdistribution.FirebaseAppDistribution; import com.google.firebase.appdistribution.FirebaseAppDistributionException; public class MainActivity extends AppCompatActivity { private static final String TAG = "AppDistribution-Quickstart"; private FirebaseAppDistribution mFirebaseAppDistribution; @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); final ActivityMainBinding binding = ActivityMainBinding.inflate(getLayoutInflater()); setContentView(binding.getRoot()); // Java 使用静态方法获取单例 mFirebaseAppDistribution = FirebaseAppDistribution.getInstance(); } @Override public void onResume() { super.onResume(); mFirebaseAppDistribution.updateIfNewReleaseAvailable() .addOnProgressListener(updateProgress -> { // （可选）实现自定义进度更新 }) .addOnFailureListener(e -> { if (e instanceof FirebaseAppDistributionException) { // 处理异常 } }); } }

4.3 关键设计解读

从源码结构可以总结出 SDK 使用上的三个关键设计：

1. 调用时机选在onResume()而非onCreate()：两个示例都把检查放在onResume()，因为测试人员可能停留在应用内较长时间，onCreate只在冷启动时触发一次；放在onResume可确保每次从后台回到前台时都会重新检查，覆盖"测试人员此刻刚好有新版本可用"的场景。
2. 初始化在onCreate、检查在onResume：FirebaseAppDistribution单例在onCreate中获取一次并保存为成员变量，避免重复获取；真正的网络检查则延迟到onResume。
3. 回调三件套：updateIfNewReleaseAvailable()返回Task，示例通过addOnProgressListener（下载进度）与addOnFailureListener（失败处理，异常类型为FirebaseAppDistributionException）挂接回调。进度监听器是可选的——SDK 默认会通过系统NotificationManager自动展示下载进度，这里的 listener 是用于在自动通知之外再叠加自定义 UI 进度（源码注释对此有明确说明）。

关于"新版本"的判定：SDK 会比较当前安装构建的版本与已分发构建的版本信息，只对测试人员账号可见的新构建触发提醒。这属于 SDK 内部行为，从示例源码中可以推断，应用侧无需（也不应该）自己实现版本比较逻辑。

5. 从拉取到安装：SDK 内部流程推演

虽然没有 SDK 源码在本仓库内，但结合官方 API 语义与示例代码，可以梳理出一次完整的新构建提醒流程：

1. 应用进入前台：onResume()触发updateIfNewReleaseAvailable()。
2. 版本检查：SDK 向 App Distribution 服务端查询，判断是否存在对当前测试人员可见的新构建。
3. 应用内提醒：若存在新构建，SDK 在应用内弹出提醒对话框（README 截图 docs/result.png 展示的正是这一步——"Enable new build alerts"弹窗，提示 "Get in-app alerts when new builds are ready to test"，并提供 "NOT NOW" 与 "TURN ON" 两个按钮）。
4. 下载与安装：测试人员确认后，SDK 负责下载新构建并引导安装；下载进度默认通过系统通知展示，同时可通过addOnProgressListener获取进度以便实现自定义 UI。

测试人员身份由 Firebase 认证体系（App Distribution 测试人员邀请机制）决定，SDK 会自动识别当前设备对应的测试人员账号。

6. 界面布局与文案

应用主界面由 activity_main.xml 定义，是一个极简的 ConstraintLayout：顶部展示 Firebase logo（@drawable/firebase_lockup_400），下方是说明文字。对应的文案定义在 strings.xml：

<string name="app_name">App Distribution Quickstart</string> <string name="textview_text">Welcome to the Firebase App Distribution Quickstart app. Press the button to trigger an analytics event!</string>

界面本身并不承载业务逻辑，它的作用是提供一个"宿主"：当 SDK 检测到新版本时，提醒弹窗会叠加在任意前台 Activity 之上。这也印证了该示例的核心目的——演示 SDK 的提醒能力，而非业务功能。

7. 构建与运行

7.1 前提条件

在构建运行前需要完成：

1. 创建 Firebase 项目并注册 Android 应用，下载google-services.json放入appdistribution/app/目录。这是 Firebase 官方 Android 集成流程的必选步骤（对应 README 中指向的官方指引），缺少该文件时com.google.gms.google-services插件会直接报错。
2. 准备好 App Distribution 测试人员账号，并至少上传一个初始构建到 Firebase 控制台，否则没有"新版本"可供检测。

7.2 构建命令

在仓库根目录使用 Gradle 包装脚本构建该模块（也可以单独在appdistribution/目录下执行./gradlew）：

# 从仓库根目录构建 appdistribution 模块 ./gradlew :appdistribution:app:assembleDebug # 或进入 appdistribution 目录后执行 cd appdistribution && ./gradlew assembleDebug

模块 SDK 配置要点（build.gradle.kts）：

• compileSdk = 37、targetSdk = 37、minSdk = 24（覆盖 Android 7.0 及以上设备）；
• multiDexEnabled = true：因为 Firebase 依赖链较长，方法数可能超过 64K，需要开启 multidex；
• Java 17 编译级别（sourceCompatibility/targetCompatibility）。

7.3 测试

仓库还包含仪器测试 InstrumentedTest.java，使用 Espresso + UIAutomator 验证弹窗在"应用回到前台"时正确显示（testFiamDisplaysOnForegroundCampaign）。不过需要注意：该测试文件的用例名与实现细节实际上更贴近 Firebase In-App Messaging 的弹窗验证逻辑，且依赖的视图 ID（collapse_button、modal_root、eventTriggerButton）在当前的 activity_main.xml 中并不存在，属于历史遗留代码。因此运行时可能会失败，建议以手工验证为主：安装应用后由测试人员账号触发一次新构建上传，观察前台是否弹出提醒。

8. 常见问题与建议

• 提醒没有弹出？优先检查：google-services.json是否就位、当前设备是否绑定了有效的测试人员账号、控制台是否确实上传了新构建（版本号高于当前安装版本）。
• 只在调试构建上验证：App Distribution 针对的是"测试分发"场景，正式发布的 release 构建通常不需要集成提醒 SDK；示例中的 release 构建类型也关闭了混淆（isMinifyEnabled = false），方便排查。
• 生产环境务必使用稳定版 SDK：示例锁定的是 beta 版本16.0.0-beta20，接入生产应用前请根据官方发布渠道升级到稳定版本。
• 谨慎对待遗留测试代码：如 7.3 节所述，androidTest下的仪器测试与当前示例界面并不匹配，参考时需要甄别，不要盲目照搬。

9. 小结

通过这个快速入门示例，你可以掌握 Firebase App Distribution Android SDK 的最小接入闭环：引入 BoM 与 SDK 依赖、在onResume中调用updateIfNewReleaseAvailable()、通过进度与失败监听处理异步结果。整个示例提供了 Java 与 Kotlin 两套等价实现，仓库内的 README 与 运行截图 可作为对照参考。在你自己的应用中接入时，把示例中的调用代码放进目标 Activity 的onResume()，并保证测试人员账号与构建上传链路就绪，即可复现完整的新版本提醒体验。

• 示例工程