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

APK AAB

您可以使用 App Distribution Gradle 插件将 App Distribution 集成到您的 Android 构建过程中。该插件允许您在应用程序的build.gradle文件中指定测试人员和发行说明，让您可以为应用程序的不同构建类型和变体配置分发。

本指南介绍如何使用 App Distribution Gradle 插件将 APK 分发给测试人员。

在你开始之前

如果您还没有，请将 Firebase 添加到您的 Android 项目中。

如果您不使用任何其他 Firebase 产品，您只需创建一个项目并注册您的应用。但是，如果您决定将来使用其他产品，请务必完成上面链接页面上的所有步骤。

注意：当您向 Firebase 注册您的应用时，请确保输入与您正在分发的应用相同的包名称。包名称值区分大小写，并且在 Firebase 中注册到您的 Firebase 项目后，您的应用无法更改。

步骤 1. 设置您的 Android 项目

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

   时髦的

   buildscript {
     repositories {
       // Make sure that you have the following two repositories
       google()  // Google's Maven repository
       mavenCentral()  // Maven Central repository
     }
   
     dependencies {
         ...
         classpath 'com.android.tools.build:gradle:7.2.0'
   
         // Make sure that you have the Google services Gradle plugin dependency
         classpath 'com.google.gms:google-services:4.3.14'
   
         // Add the dependency for the App Distribution Gradle plugin
         classpath 'com.google.firebase:firebase-appdistribution-gradle:3.1.1'
     }
   }
   

   科特林

   buildscript {
     repositories {
       // Make sure that you have the following two repositories
       google()  // Google's Maven repository
       mavenCentral()  // Maven Central repository
     }
   
     dependencies {
         ...
         classpath("com.android.tools.build:gradle:7.2.0")
   
         // Make sure that you have the Google services Gradle plugin dependency
         classpath("com.google.gms:google-services:4.3.14")
   
         // Add the dependency for the App Distribution Gradle plugin
         classpath("com.google.firebase:firebase-appdistribution-gradle:3.1.1")
     }
   }
   

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

   时髦的

   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'
   }
   

   科特林

   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")
   }
   

3. 如果您位于公司代理或防火墙后面，请添加以下Java 系统属性，以使 App Distribution 能够将您的分配上传到 Firebase：

   -Djavax.net.ssl.trustStore=/path/to/truststore -Djavax.net.ssl.trustStorePassword=password
   

第 2 步：使用 Firebase 进行身份验证

注意： App Distribution 已弃用 Gradle 插件的 Google 帐户登录功能。此功能将于 2023 年第一季度移除。

在您可以使用 Gradle 插件之前，您必须首先通过以下方式之一对您的 Firebase 项目进行身份验证。默认情况下，如果没有使用其他身份验证方法，Gradle 插件会从 Firebase CLI 中查找凭据。

使用 Firebase 服务帐号凭据

使用服务帐户进行身份验证允许您灵活地将该插件与您的持续集成 (CI) 系统一起使用。提供服务帐户凭据的方法有两种：

• 将您的服务帐户密钥文件传递给build.gradle 。如果您的构建环境中已经有服务帐户密钥文件，您可能会发现此方法很方便。
• 将环境变量GOOGLE_APPLICATION_CREDENTIALS设置为指向您的服务帐户密钥文件。如果您已经为其他 Google 服务（例如，Google Cloud）配置了应用程序默认凭据 (ADC)，您可能更喜欢这种方法。

要使用服务帐户凭据进行身份验证：

1. 在Google Cloud Console 上，选择您的项目并创建一个新的服务帐户。
2. 添加Firebase 应用分发管理员角色。
3. 创建一个私有 json 密钥并将该密钥移动到您的构建环境可以访问的位置。请务必将此文件保存在安全的地方，因为它授予管理员访问 Firebase 项目中 App Distribution 的权限。
4. 如果您在 2019 年 9 月 20 日之后创建应用，请跳过此步骤：在 Google API 控制台中，启用Firebase App Distribution API。出现提示时，选择与您的 Firebase 项目同名的项目。

5. 提供或找到您的服务帐户凭据：

   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或<project>/<app-module>/build.gradle.kts ）中，通过添加至少一个firebaseAppDistribution部分。

例如，要将release版本分发给测试人员，请遵循以下说明：

时髦的

android {

  // ...

  buildTypes {
      release {
          firebaseAppDistribution {
              artifactType="APK"
              releaseNotesFile="/path/to/releasenotes.txt"
              testers="[e-mail], [e-mail], [e-mail]"
          }
      }
  }

  // ...
}

科特林

注意：要使用 Kotlin DSL，您必须使用 3.1.0 或更高版本的 App Distribution Gradle 插件。

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

android {

  // ...

  buildTypes {
      release {
          firebaseAppDistribution {
              artifactType = "APK"
              releaseNotesFile = "/path/to/releasenotes.txt"
              testers = "[e-mail], [e-mail], [e-mail]"
          }
      }
  }

  // ...
}

您可以为构建类型和产品风格配置 App Distribution。

例如，要以“演示”和“完整”产品风格分发debug和release版本，请遵循以下说明：

时髦的

android {

  // ...

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

  flavorDimensions "version"
  productFlavors {
      demo {
          dimension "version"
          firebaseAppDistribution {
              releaseNotes="Release notes for demo version"
              testers="[e-mail]"
          }
      }
      full {
          dimension "version"
          firebaseAppDistribution {
              releaseNotes="Release notes for full version"
              testers="[e-mail]"
          }
      }
  }

  // ...
}

科特林

注意：要使用 Kotlin DSL，您必须使用 3.1.0 或更高版本的 App Distribution Gradle 插件。

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 = "[e-mail]"
          }
      }
      create("full") {
          dimension = "version"
          firebaseAppDistribution {
              releaseNotes = "Release notes for full version"
              testers = "[e-mail]"
          }
      }
  }

  // ...
}

使用以下参数配置分布：

应用分发构建参数
appId	您应用的 Firebase 应用 ID。仅当您没有安装 Google Services Gradle 插件时才需要。您可以在google-services.json文件或 Firebase 控制台的常规设置页面中找到应用 ID。 build.gradle文件中的值会覆盖google-services插件的输出值。 appId="1:1234567890:android:321abc456def7890"
serviceCredentialsFile	您的服务帐号私钥 JSON 文件的路径。仅当您使用服务帐户身份验证时才需要。
artifactType	指定应用的文件类型。可以设置为"AAB"或"APK" 。
artifactPath	要上传的 APK 或 AAB 文件的绝对路径。
releaseNotes或releaseNotesFile	此版本的发行说明。 您可以直接指定发行说明，也可以指定纯文本文件的路径。
testers或测试人员testersFile	您要将构建分发到的测试人员的电子邮件地址。 您可以将测试人员指定为以逗号分隔的电子邮件地址列表： testers="[e-mail], [e-mail], [e-mail]" 或者，您可以指定包含以逗号分隔的电子邮件地址列表的文件的路径： testersFile="/path/to/testers.txt"
groups或groupsFile	您要将构建分发到的测试人员组（请参阅管理测试人员）。组使用指定组别名，您可以在 Firebase 应用分发控制台的“测试人员”选项卡中找到它。 您可以将组指定为以逗号分隔的组别名列表： groups="qa-team, android-testers" 或者，您可以指定包含逗号分隔的组别名列表的文件的路径： groupsFile="/path/to/tester-groups.txt"
stacktrace	打印出用户异常的堆栈跟踪。这在调试问题时很有帮助。

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

1. 最后，要打包您的测试应用并邀请测试人员，请使用项目的 Gradle 包装器构建目标BUILD-VARIANT和appDistributionUpload BUILD-VARIANT ，其中BUILD-VARIANT是您在上一步中配置的可选产品风格和构建类型。有关产品风味的更多信息，请参阅配置构建变体。

   例如，要使用release版本变体分发您的应用程序，请运行以下命令：

   ./gradlew assembleRelease appDistributionUploadRelease
   

   或者，如果您使用Google 帐户进行了身份验证并且没有在 Gradle 构建文件中提供凭据，请包含FIREBASE_TOKEN变量：

   export FIREBASE_TOKEN=1/a1b2c3d4e5f67890
   ./gradlew --stop // Only needed for environment variable changes
   ./gradlew assembleRelease appDistributionUploadRelease
   

2. 您还可以通过以--<property-name>=<property-value>的形式传递命令行参数来覆盖build.gradle文件中设置的值。例如：

   • 要将调试版本上传到 App Distribution：

     ./gradlew bundleDebug appDistributionUploadDebug
         --artifactType="APK"
     

   • 要从您的 Firebase 项目中邀请更多测试人员或移除现有测试人员，请执行以下操作：

     ./gradlew appDistributionAddTesters
         --projectNumber=<project_number>
         --emails="[e-mail], [e-mail]"
     ./gradlew appDistributionRemoveTesters
         --projectNumber=<project_number>
         --emails="[e-mail], [e-mail]"
     

     将测试人员添加到您的 Firebase 项目后，您可以将其添加到各个版本中。被移除的测试人员将无法再访问您项目中的版本，但仍可能在一段时间内保留对您的版本的访问权限。

   您还可以使用--file="/path/to/testers.txt"而不是--emails指定测试人员。

   appDistributionAddTesters和appDistributionRemoveTesters任务也接受以下参数：

   • projectNumber ：您的 Firebase 项目编号。

   • serviceCredentialsFile ：您的 Google 服务凭据文件的路径。这与上传操作使用的参数相同。

分发构建后，它会在 Firebase 控制台的 App Distribution 仪表板中可用 150 天（五个月）。当构建距离到期 30 天时，控制台和测试人员在其测试设备上的构建列表中都会显示到期通知。

未受邀测试应用程序的测试人员会收到电子邮件邀请以开始使用，现有测试人员会收到电子邮件通知，表明新版本已准备好进行测试（请阅读测试人员设置指南以获取有关如何安装测试应用程序的说明）。您可以在 Firebase 控制台中监控每个测试人员的状态——他们是否接受了邀请以及是否下载了应用程序。

测试人员有 30 天的时间在应用程序过期前接受测试邀请。当邀请距过期还有 5 天时，过期通知会出现在 Firebase 控制台中某个版本的测试人员旁边。可以通过使用测试人员行上的下拉菜单重新发送邀请来更新邀请。

下一步

• 访问Android App Bundle 代码实验室，了解如何逐步分发 App Bundle 版本。

• 了解使用 CI/CD 将 Android 应用程序分发给 QA 测试人员的最佳实践。