使用 Gradle 将 Android 应用分发给测试人员

使用 App Distribution Gradle 插件将 App Distribution 集成到 Android 构建流程中。利用该插件，您可以在应用的 Gradle 文件中指定测试人员和版本说明，从而针对应用的不同 build 类型和变体配置分发。

本指南介绍如何使用 App Distribution Gradle 插件将 Android App Bundle (AAB) 分发给测试人员。

App Distribution 与 Google Play 的内部应用分享服务相集成，可处理您上传的 AAB 文件，并提供专门根据您的测试人员设备配置而优化的 APK。通过分发 AAB 文件，您可以实现以下目标：

运行专门根据您的测试人员设备而优化的 APK（由 Google Play 提供）。
发现并调试设备特定的问题。
测试 App Bundle 功能，例如 Play Feature Delivery 和 Play Asset Delivery。
减少测试人员下载文件的大小。

所需权限

如需将 AAB 文件上传到 App Distribution，您必须将您的 Firebase 应用与 Google Play 中的应用相关联。您必须拥有所需的访问权限级别才能执行这些操作。

如果您没有必需的 Firebase 访问权限，可以请求 Firebase Project Owner 通过 Firebase 控制台 IAM 设置为您分配合适的角色。如果您对访问 Firebase 项目（包括查找或分配 Owner）有疑问，请查看“权限设置和 Firebase 项目访问权限”常见问题解答。

下表适用于将 Firebase 应用与 Google Play 中的应用相关联以及上传 AAB 文件这两个场景。

Firebase 控制台中的操作	所需的 IAM 权限	默认包含所需权限的 IAM 角色	其他必需的角色
将 Firebase 应用与 Google Play 中的应用相关联	`firebase.playLinks.update`	拥有下列任一角色： Owner Firebase Admin	以管理员身份访问 Google Play 开发者账号
将 AAB 文件上传到 App Distribution	`firebaseappdistro.releases.update`	拥有下列任一角色： Owner Editor Firebase Admin Firebase Quality Admin Firebase App Distribution Admin	––

准备工作

将 Firebase 添加到您的 Android 项目（如果尚未添加）。在此工作流结束时，您的 Firebase 项目中就有了一个 Firebase Android 应用。

如果您没有使用任何其他 Firebase 产品，只需创建一个项目并注册应用。如果您决定使用其他产品，请务必完成将 Firebase 添加到您的 Android 项目中的所有步骤。

注意：向 Firebase 注册应用时，请输入与您要分发的应用相同的软件包名称。软件包名称值区分大小写。当您向 Firebase 项目注册您的应用后，便无法在 Firebase 中更改该值。
如需创建关联到 Google Play 的 Firebase 链接并上传 AAB 文件，请确保您的应用满足以下要求：
- Google Play 中的应用和 Firebase Android 应用均使用同一软件包名称进行注册。
  
  注意：您可以为与正式版应用有不同软件包名称的应用上传 AAB 文件。只需在 Google Play 中新建一个应用，并将其分发到任何轨道（您无需选择正式版轨道）。然后，Google Play 会使用 AAB 文件中的软件包名称注册该 Google Play 应用。
- Google Play 中的应用在应用信息中心内设置，并发布到某个 Google Play 轨道（内部测试、封闭式测试、开放式测试或正式版）。
- 该应用在 Google Play 中的审核已完成，且已发布。如果“应用状态”列显示以下状态之一，表明您的应用已发布：内部测试（非草稿内部测试）、封闭式测试、开放式测试或正式版。
将您的 Firebase Android 应用关联至您的 Google Play 开发者账号：
1. 在 Firebase 控制台中，转到您的项目设置，然后选择“集成”标签页。
2. 在“Google Play”卡片中，点击关联。
  如果您已有指向 Google Play 的链接，请改为点击管理。
3. 按照屏幕上的说明启用 App Distribution 集成，并选择要与 Google Play 关联的 Firebase Android 应用。
详细了解如何关联到 Google Play。

第 1 步：设置 Android 项目

在您的根级（项目级）Gradle 文件（<project>/build.gradle.kts 或 <project>/build.gradle）中，将 App Distribution Gradle 插件添加为依赖项：

Kotlin

您是否还在使用 buildscript 语法？了解如何使用该语法添加 Firebase 插件。

plugins {
    // ...
    id("com.android.application") version "7.3.0" apply false

    // Make sure that you have the Google services Gradle plugin dependency
    id("com.google.gms.google-services") version "4.4.2" apply false

    // Add the dependency for the App Distribution Gradle plugin
    id("com.google.firebase.appdistribution") version "5.0.0" apply false
}

Groovy

您是否还在使用 buildscript 语法？了解如何使用该语法添加 Firebase 插件。

plugins {
    // ...
    id 'com.android.application' version '7.3.0' apply false

    // Make sure that you have the Google services Gradle plugin dependency
    id 'com.google.gms.google-services' version '4.4.2' apply false

    // Add the dependency for the App Distribution Gradle plugin
    id 'com.google.firebase.appdistribution' version '5.0.0' apply false
}

在您的模块（应用级）Gradle 文件（通常是 <project>/<app-module>/build.gradle.kts 或 <project>/<app-module>/build.gradle）中，添加 App Distribution Gradle 插件：

Kotlin

plugins {
  id("com.android.application")

  // Make sure that you have the Google services Gradle plugin
  id("com.google.gms.google-services")

  // Add the App Distribution Gradle plugin
  id("com.google.firebase.appdistribution")
}

Groovy

plugins {
  id 'com.android.application'

  // Make sure that you have the Google services Gradle plugin
  id 'com.google.gms.google-services'

  // Add the App Distribution Gradle plugin
  id 'com.google.firebase.appdistribution'
}

如果您受公司代理或防火墙保护，请添加以下 Java 系统属性，以使 App Distribution 能够将您的分发上传到 Firebase：
```
-Djavax.net.ssl.trustStore=/path/to/truststore -Djavax.net.ssl.trustStorePassword=password
```

第 2 步：进行 Firebase 身份验证

您必须首先通过以下方法之一对 Firebase 项目进行身份验证，然后才能使用 Gradle 插件。默认情况下，若未使用其他身份验证方法，Gradle 插件会从 Firebase CLI 查找凭据。

使用 Firebase 服务账号凭据

您可以使用服务账号进行身份验证，这样就能灵活将插件与持续集成 (CI) 系统配合使用。您可以通过两种方式来提供服务账号凭据：

将您的服务账号密钥文件传递给 build.gradle。如果您已在构建环境中拥有服务账号密钥文件，则可能会发现此方法很便捷。
将 GOOGLE_APPLICATION_CREDENTIALS 环境变量设置为指向您的服务账号密钥文件。在下面的情况下，您可能会倾向于使用此方法：如果您已为其他 Google 服务配置了应用默认凭据 (ADC)，例如以下服务：Google Cloud）。

如需使用服务账号凭据进行身份验证，请执行以下操作：

在 Google Cloud 控制台中，选择您的项目并创建一个新的服务账号。
添加 Firebase App Distribution Admin 角色。
创建一个 JSON 私钥并将其移到构建环境可访问的位置。请务必将此文件保存在安全的位置，因为它会向管理员授予对您 Firebase 项目中 App Distribution 的访问权限。
如果您是在 2019 年 9 月 20 日之后创建的应用，请跳过此步骤：在 Google API 控制台中，启用 Firebase App Distribution API。出现提示时，请选择与您的 Firebase 项目同名的项目。
提供或查找您的服务账号凭据：
1. 如需将您的服务账号密钥传递给 Gradle，请在 build.gradle 文件中将属性 serviceCredentialsFile 设置为私钥 JSON 文件。
2. 如需使用 ADC 查找凭据，请将环境变量 GOOGLE_APPLICATION_CREDENTIALS 设置为私钥 JSON 文件的路径。例如：
```
 export GOOGLE_APPLICATION_CREDENTIALS=/absolute/path/to/credentials/file.json
```
  如需详细了解如何使用 ADC 进行身份验证，请参阅向您的应用提供凭据。

使用 Firebase CLI 登录

如需了解如何对项目进行身份验证，请参阅使用 Firebase CLI 登录。

第 3 步：配置您的分发属性

在模块（应用级）Gradle 文件（通常为 <project>/<app-module>/build.gradle.kts 或 <project>/<app-module>/build.gradle）中，通过添加至少 1 个 firebaseAppDistribution 部分来配置 App Distribution。

例如，如需将 release build 分发给测试人员，请按照以下说明操作：

Kotlin

import com.google.firebase.appdistribution.gradle.firebaseAppDistribution

android {

  // ...

  buildTypes {
      getByName("release") {
          firebaseAppDistribution {
              artifactType = "AAB"
              releaseNotesFile = "/path/to/releasenotes.txt"
              testers = "ali@example.com, bri@example.com, cal@example.com"
          }
      }
  }

  // ...
}

Groovy

android {

  // ...

  buildTypes {
      release {
          firebaseAppDistribution {
              artifactType="AAB"
              releaseNotesFile="/path/to/releasenotes.txt"
              testers="ali@example.com, bri@example.com, cal@example.com"
          }
      }
  }

  // ...
}

您可以针对 build 类型和产品变种配置 App Distribution。

例如，如需分发采用“演示”和“完整”产品变种的 debug 和 release build，请按照以下说明操作：

Kotlin

import com.google.firebase.appdistribution.gradle.firebaseAppDistribution

android {

  // ...

  buildTypes {
      getByName("debug") {...}
      getByName("release") {...}
  }

  flavorDimensions += "version"
  productFlavors {
      create("demo") {
          dimension = "version"
          firebaseAppDistribution {
              releaseNotes = "Release notes for demo version"
              testers = "demo@testers.com"
          }
      }
      create("full") {
          dimension = "version"
          firebaseAppDistribution {
              releaseNotes = "Release notes for full version"
              testers = "full@testers.com"
          }
      }
  }

  // ...
}

Groovy

android {

  // ...

  buildTypes {
      debug {...}
      release {...}
  }

  flavorDimensions "version"
  productFlavors {
      demo {
          dimension "version"
          firebaseAppDistribution {
              releaseNotes="Release notes for demo version"
              testers="demo@testers.com"
          }
      }
      full {
          dimension "version"
          firebaseAppDistribution {
              releaseNotes="Release notes for full version"
              testers="full@testers.com"
          }
      }
  }

  // ...
}

请使用以下参数配置分发：

App Distribution Build 参数
`appId`	您的应用的 Firebase 应用 ID。只有在您未安装 Google 服务 Gradle 插件时才需要此 ID。您可以在 `google-services.json` 文件中或在 Firebase 控制台的“常规设置”页面中找到此应用 ID。您的 `build.gradle` 文件中的值会覆盖 `google-services` 插件的输出值。 appId="1:1234567890:android:321abc456def7890"
`serviceCredentialsFile`	服务账号私钥 JSON 文件的路径。只有在使用服务账号身份验证时才需要此参数。
`artifactType`	指定应用的文件类型。可以设置为 `"AAB"` 或 `"APK"`。
`artifactPath`	您要上传的 APK 或 AAB 文件的绝对路径。
`releaseNotes` 或 `releaseNotesFile`	此 build 的版本说明。您可以直接指定版本说明，或指定一个纯文本文件的路径。
`testers` 或 `testersFile`	您要向其分发构建版本的测试人员的电子邮件地址。您可以采用英文逗号分隔电子邮件地址列表的形式来指定测试人员： testers="ali@example.com, bri@example.com, cal@example.com" 或者，您也可以指定一个文件的路径，该文件包含以英文逗号分隔的电子邮件地址列表： testersFile="/path/to/testers.txt"
`groups` 或 `groupsFile`	您要向其分发构建版本的测试人员群组（请参阅管理测试人员）。使用群组别名指定群组，您可以在 Firebase App Distribution 控制台的测试人员标签页中查找群组别名。您可以采用以英文逗号分隔的群组别名列表的形式来指定群组： groups="qa-team, android-testers" 或者，您也可以指定一个文件的路径，该文件包含以英文逗号分隔的群组别名列表： groupsFile="/path/to/tester-groups.txt"
`testDevices` 或 `testDevicesFile`	以下分发类型属于自动化测试助手 Beta 版功能的一部分。您要向其分发 build 的测试设备（请参阅自动化测试）。您可以采用以英文分号分隔的设备规格列表的形式指定测试设备： testDevices="model=shiba,version=34,locale=en,orientation=portrait;model=b0q,version=33,locale=en,orientation=portrait" 或者，您可以指定一个文件的路径，该文件包含以英文分号分隔的设备规格列表： testDevicesFile="/path/to/testDevices.txt"
`testUsername`	在自动化测试期间要使用的自动登录的用户名。
`testPassword` 或 `testPasswordFile`	在自动化测试期间要使用的自动登录的密码。或者，您可以指定一个纯文本文件的路径，该文件包含密码： testPasswordFile="/path/to/testPassword.txt"
`testUsernameResource`	在自动化测试期间要使用的自动登录的用户名字段的资源名称。
`testPasswordResource`	在自动化测试期间要使用的自动登录的密码字段的资源名称。
`testNonBlocking`	异步运行自动化测试。访问 Firebase 控制台查看自动测试结果。
`stacktrace`	输出用户异常的堆栈轨迹。这在调试问题时很有用。

第 4 步：将您的应用分发给测试人员

最后，如需封装测试应用并邀请测试人员，请使用项目的 Gradle 封装容器来构建目标 BUILD-VARIANT 和 appDistributionUploadBUILD-VARIANT，其中 BUILD-VARIANT 是您在上一步配置的可选产品变种和 build 类型。如需详细了解产品变种，请参阅配置 build 变体。

例如，要使用 release build 变体分发您的应用，请运行以下命令：
```
./gradlew bundleRelease appDistributionUploadRelease
```
或者，如果您已使用 Google 账号进行身份验证并且未在 Gradle build 文件中提供凭据，请添加 FIREBASE_TOKEN 变量：
```
export FIREBASE_TOKEN=1/a1b2c3d4e5f67890
./gradlew --stop // Only needed for environment variable changes
./gradlew bundleRelease appDistributionUploadRelease
```
您还可以通过传递 --<property-name>=<property-value> 形式的命令行参数来覆盖 build.gradle 文件中设置的值。例如：
- 如需将调试 build 上传到 App Distribution，请执行以下操作：
```
./gradlew bundleDebug appDistributionUploadDebug
    --artifactType="AAB"
```
- 如需邀请其他测试人员或从 Firebase 项目中移除现有测试人员，请执行以下操作：
```
./gradlew appDistributionAddTesters
    --projectNumber=<project_number>
    --emails="anothertester@email.com, moretesters@email.com"
./gradlew appDistributionRemoveTesters
    --projectNumber=<project_number>
    --emails="anothertester@email.com, moretesters@email.com"
```
  将测试人员添加到 Firebase 项目后，您可以将其添加到各个版本中。被移除的测试人员将无法再访问项目中的版本，但仍可能在一段时间内保留对这些版本的访问权限。
您还可以使用 --file="/path/to/testers.txt"（而非 --emails）指定测试人员。

appDistributionAddTesters 和 appDistributionRemoveTesters 任务也接受以下参数：
- projectNumber：您的 Firebase 项目编号。
- serviceCredentialsFile：Google 服务凭据文件的路径。此参数与上传操作使用的参数相同。

Gradle 插件会在上传版本后输出以下链接。这些链接可帮助您管理二进制文件，并确保测试人员和其他开发者拥有正确的版本：

firebase_console_uri - 指向显示单个版本的 Firebase 控制台的链接。您可以将此链接分享给贵组织中的其他开发者。
testing_uri - 测试人员体验（Android 原生应用）中的版本链接，可让测试人员查看版本说明并将应用安装到设备上。测试人员需要有权访问相应版本才能使用该链接。
binary_download_uri - 用于直接下载并安装应用二进制文件（APK 或 AAB 文件）的签名链接。该链接会在 1 小时后过期。

当您分发 build 后，在 150 天（5 个月）内均可在 Firebase 控制台的 App Distribution 信息中心中访问它。当该 build 距离过期还有 30 天的时候，Firebase 控制台中和测试人员的测试设备上的 build 列表中都会显示到期通知。

之前未受邀测试应用的测试人员会收到邀请其开始测试的电子邮件，而现有测试人员将收到有关新 build 已可供测试的电子邮件通知（请参阅测试人员设置指南了解如何安装测试应用）。您可以在 Firebase 控制台中监控每个测试人员的状态：他们是否接受了邀请以及是否下载了应用。

在邀请到期前，测试人员有 30 天的时间来接受测试应用的邀请。当邀请距离到期还有 5 天的时候，Firebase 控制台会在相应版本的测试人员旁边显示到期通知。您可以使用测试人员对应行中的下拉菜单重发邀请来重新开始邀请测试人员。

后续步骤

实现应用内反馈，以便测试人员轻松发送有关应用的反馈（包括屏幕截图）。
了解如何在有新的应用 build 可供安装时向测试人员显示相应的应用内提醒。
请访问 Android App Bundle Codelab，逐步了解如何分发 App Bundle 版本。
了解使用 CI/CD 将 Android 应用分发给质量检查测试人员的最佳实践。