You can integrate App Distribution into your Android build process using the
App Distribution Gradle plugin. The plugin lets you specify your testers and
release notes in your app's Gradle file, letting you configure distributions
for different build types and variants of your app.
This guide describes how to distribute APKs to testers using the
App Distribution Gradle plugin.
## Before you begin
1. If you haven't already, [add Firebase to your Android
project](https://firebase.google.com/docs/android/setup#console).
If you aren't using any other Firebase products, you only have to create a
project and register your app. However, if you decide to use additional
products in the future, be sure to complete all of the steps on the page
linked above.
> [!CAUTION]
> **Caution:** When you register your app with Firebase, make sure to enter the same package name as the app you're distributing. The package name value is case-sensitive and cannot be changed for your app in Firebase after it's registered with your Firebase project.
2. Open the [App Distribution page](https://console.firebase.google.com/project/_/appdistribution) of the
Firebase console. Select your Firebase project when prompted, select
your app using the app switcher, and click **Get started**.
## Step 1. Set up your Android project
1. In your **root-level (project-level)** Gradle file
(`/build.gradle.kts` or `/build.gradle`), add the
App Distribution Gradle plugin as a dependency:
### Kotlin
> [!NOTE]
> Are you still using the `buildscript` syntax? Learn how to [add Firebase plugins](https://firebase.google.com/docs/android/troubleshooting-faq.md.txt#add-plugins-using-buildscript-syntax) using that syntax.
```kotlin
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.5.0" apply false
// Add the dependency for the App Distribution Gradle plugin
id("com.google.firebase.appdistribution") version "5.3.1" apply false
}
```
### Groovy
> [!NOTE]
> Are you still using the `buildscript` syntax? Learn how to [add Firebase plugins](https://firebase.google.com/docs/android/troubleshooting-faq.md.txt#add-plugins-using-buildscript-syntax) using that syntax.
```groovy
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.5.0' apply false
// Add the dependency for the App Distribution Gradle plugin
id 'com.google.firebase.appdistribution' version '5.3.1' apply false
}
```
2. In your **module (app-level)** Gradle file (usually
`//build.gradle.kts` or
`//build.gradle`),
add the App Distribution Gradle plugin:
### Kotlin
```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
```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'
}
```
3. If you're behind a corporate proxy or firewall, add the following
[Java system property](https://docs.gradle.org/current/userguide/build_environment.html#sec:gradle_system_properties)
that enables App Distribution to upload your distributions to Firebase:
```java
-Djavax.net.ssl.trustStore=/path/to/truststore -Djavax.net.ssl.trustStorePassword=password
```
## Step 2. Authenticate with Firebase
Before you can use the Gradle plugin, you must first authenticate with your
Firebase project in one of the following ways. By default, the Gradle plugin
looks for credentials from the Firebase CLI if no other authentication
method is used.
### Use Firebase service account credentials
Authenticating with a service account allows you to flexibly use the plugin with
your continuous integration (CI) system. There are two ways to provide service
account credentials:
- Pass your service account key file to `build.gradle`. You might find this method convenient if you already have your service account key file in your build environment.
- Set the environment variable `GOOGLE_APPLICATION_CREDENTIALS` to point to your service account key file. You might prefer this method if you already have Application Default Credentials (ADC) configured for another Google service (e.g., Google Cloud).
To authenticate using service account credentials:
1. On the [Google Cloud console,](https://console.cloud.google.com/projectselector2/iam-admin/serviceaccounts) select your project and create a new service account.
2. Add the **Firebase App Distribution Admin** role.
3. Create a private json key and move the key to a location accessible to your build environment. *Be sure to keep this file somewhere safe* , as it grants administrator access to App Distribution in your Firebase project.
4. Skip this step if you created your app after September 20, 2019: In the Google APIs console, enable the [Firebase App Distribution API.](https://console.developers.google.com/apis/api/firebaseappdistribution.googleapis.com/overview?project=_) When prompted, select the project with the same name as your Firebase project.
5. Provide or locate your service account credentials:
1. To pass Gradle your service account key, in your `build.gradle` file, set the property `serviceCredentialsFile` to the private key JSON file.
2. To locate your credentials with ADC, set the environment variable
`GOOGLE_APPLICATION_CREDENTIALS` to the path for the private key JSON
file. For example:
```
export GOOGLE_APPLICATION_CREDENTIALS=/absolute/path/to/credentials/file.json
```
For more information on authenticating with ADC, read [Providing credentials to your
application.](https://cloud.google.com/docs/authentication/production#providing_credentials_to_your_application)
### Sign in using the Firebase CLI
See [Log in with the Firebase CLI](https://firebase.google.com/docs/cli.md.txt#sign-in-test-cli)
for instructions on how to authenticate your project.
## Step 3. Configure your distribution properties
In your **module (app-level)** Gradle file (usually
`//build.gradle.kts` or
`//build.gradle`), configure App Distribution by adding
at least one `firebaseAppDistribution` section.
For example, to distribute the `release` build to testers, follow these
instructions::
### Kotlin
> [!NOTE]
> **Note:** To use Kotlin DSL, you must use version 3.1.0 or greater of the App Distribution Gradle plugin.
```kotlin
import com.google.firebase.appdistribution.gradle.firebaseAppDistribution
android {
// ...
buildTypes {
getByName("release") {
firebaseAppDistribution {
artifactType = "APK"
releaseNotesFile = "/path/to/releasenotes.txt"
testers = "ali@example.com, bri@example.com, cal@example.com"
}
}
}
// ...
}
```
### Groovy
```
android {
// ...
buildTypes {
release {
firebaseAppDistribution {
artifactType="APK"
releaseNotesFile="/path/to/releasenotes.txt"
testers="ali@example.com, bri@example.com, cal@example.com"
}
}
}
// ...
}
```
You can configure App Distribution for [build types and product flavors](https://developer.android.com/studio/build/build-variants).
For example, to distribute `debug` and `release` builds in "demo" and "full"
product flavors, follow these instructions:
### Kotlin
> [!NOTE]
> **Note:** To use Kotlin DSL, you must use version 3.1.0 or greater of the App Distribution Gradle plugin.
```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"
}
}
}
// ...
}
```
Use the following parameters to configure the distribution:
| App Distribution Build Parameters ||
|---|---|
| `appId` | Your app's Firebase App ID. Required only if you don't have the Google Services Gradle plugin installed. You can find the App ID in the `google-services.json` file or in the Firebase console on the [General Settings page](https://console.firebase.google.com/project/_/settings/general/). The value in your `build.gradle` file overrides the value output from the `google-services` plugin. ``` appId="1:1234567890:android:321abc456def7890" ``` |
| `serviceCredentialsFile` | The path to your service account private key JSON file. Required only if you use service account authentication. |
| `artifactType` | Specifies your app's file type. Can be set to `"AAB"` or `"APK"`. |
| `artifactPath` | Absolute path to the APK or AAB file you want to upload. |
| `releaseNotes` or `releaseNotesFile` | Release notes for this build. You can either specify the release notes directly or the path to a plain text file. |
| `testers` or `testersFile` | The email addresses of the testers you want to distribute builds to. You can specify the testers as a comma-separated list of email addresses: ``` testers="ali@example.com, bri@example.com, cal@example.com" ``` Or, you can specify the path to a file containing a comma-separated list of email addresses: ``` testersFile="/path/to/testers.txt" ``` |
| `groups` or `groupsFile` | The tester groups you want to distribute builds to (see [Manage testers](https://firebase.google.com/docs/app-distribution/manage-testers)). Groups are specified using group aliases, which you can find in the **Testers** tab in the Firebase App Distribution console. You can specify the groups as a comma-separated list of group aliases: ``` groups="qa-team, android-testers" ``` Or, you can specify the path to a file containing a comma-separated list of group aliases: ``` groupsFile="/path/to/tester-groups.txt" ``` |
| `testDevices` or `testDevicesFile` | The test devices you want to run [App Testing agent](https://firebase.google.com/docs/app-distribution/app-testing-agent) tests on. You can specify the test devices as a semicolon-separated list of device specifications: ``` testDevices="model=shiba,version=34,locale=en,orientation=portrait" ``` Or, you can specify the path to a file containing a semicolon-separated list of device specifications: ``` testDevicesFile="/path/to/testDevices.txt" ``` |
| `testUsername` | The username for automatic login to be used during [App Testing agent](https://firebase.google.com/docs/app-distribution/app-testing-agent) tests. |
| `testPassword` or `testPasswordFile` | The password for automatic login to be used during [App Testing agent](https://firebase.google.com/docs/app-distribution/app-testing-agent) tests. Or, you can specify the path to a plain text file containing a password: ``` testPasswordFile="/path/to/testPassword.txt" ``` |
| `testUsernameResource` | Resource name for the username field for automatic login to be used during [App Testing agent](https://firebase.google.com/docs/app-distribution/app-testing-agent) tests. |
| `testPasswordResource` | Resource name for the password field for automatic login to be used during [App Testing agent](https://firebase.google.com/docs/app-distribution/app-testing-agent) tests. |
| `testNonBlocking` | If set when running [App Testing agent](https://firebase.google.com/docs/app-distribution/app-testing-agent) tests, the command will start the tests and then return immediately instead of waiting for them to complete. To see the test results, visit the Firebase console. If this flag is not set, the command will block until the tests are complete, and exit with a failure code if any of the tests fail. |
| `resultsBucket` | A custom Google Cloud Storage (GCS) bucket where test results are stored. If left blank, the default bucket is used. The bucket must be owned by a billing-enabled project, and specifying a bucket results in billing charges for the storage used. |
| `stacktrace` | Prints out the stacktrace for user exceptions. This is helpful when debugging issues. |
## Step 4. Distribute your app to testers
1. Finally, to package your test app and invite testers, build the targets
`BUILD-VARIANT` and
`appDistributionUploadBUILD-VARIANT` with your
project's Gradle wrapper, where BUILD-VARIANT is the optional
product flavor and build type you configured in the previous step. For more
information about product flavors, see [Configure build
variants](https://developer.android.com/studio/build/build-variants).
For example, to distribute your app using the `release` build variant, run
the following command:
```
./gradlew assembleRelease appDistributionUploadRelease
```
Or, if you authenticated with your [Google Account](https://firebase.google.com/docs/app-distribution/android/distribute-gradle.md.txt#google-acc-gradle)
and didn't provide credentials in your Gradle build file, include the
`FIREBASE_TOKEN` variable:
```
export FIREBASE_TOKEN=1/a1b2c3d4e5f67890
./gradlew --stop // Only needed for environment variable changes
./gradlew assembleRelease appDistributionUploadRelease
```
2. You can also override the values set in your `build.gradle` file by passing
command line arguments in the form of
`--=`. For example:
- To upload a debug build to App Distribution:
```bash
./gradlew bundleDebug appDistributionUploadDebug
--artifactType="APK"
```
- To invite additional testers or remove existing testers from your Firebase
project:
```bash
./gradlew appDistributionAddTesters
--projectNumber=
--emails="anothertester@email.com, moretesters@email.com"
./gradlew appDistributionRemoveTesters
--projectNumber=
--emails="anothertester@email.com, moretesters@email.com"
```
Once a tester has been added to your Firebase project, you can add them to
individual releases. Testers who are removed will no longer have access to
releases in your project, but may still retain access to your releases
for a window of time.
You can also specify testers using `--file="/path/to/testers.txt"` instead of
`--emails`.
The `appDistributionAddTesters` and `appDistributionRemoveTesters` tasks
also accept the following arguments:
- `projectNumber`: Your Firebase project number.
- `serviceCredentialsFile`: The path to your Google service credentials file.
This is the same argument used by the upload action.
The Gradle plugin outputs the following links after the release upload. These
links help you manage binaries and ensure that testers and other developers
have the right release:
- `firebase_console_uri` - A link to the Firebase console displaying a single release. You can share this link with other developers in your org.
- `testing_uri` - A link to the release in the tester experience (built-in Android app) that lets testers view release notes and install the app onto their device. The tester needs access to the release in order to use the link.
- `binary_download_uri` - A signed link that directly downloads and installs the app binary (APK or AAB file). The link expires after one hour.
Once you distribute your build, it becomes available in the
App Distribution dashboard of the Firebase console for 150 days (five months).
When the build is 30 days from expiring, an expiration notice appears in both
the console and your tester's list of builds on their test device.
Testers who haven't been invited to test the app receive email invitations to
get started, and existing testers receive email notifications that a new build
is ready to test (read the
[tester set up guide](https://firebase.google.com/docs/app-distribution/android/set-up-for-testing)
for instructions on how to install the test
app). You can monitor the status of each tester-whether they accepted the
invitation and whether they downloaded the app-in the Firebase console.
Testers have 30 days to accept an invitation to test the app before it expires.
When an invitation is 5 days from expiring, an expiration notice appears in the
Firebase console next to the tester on a release. An invitation can be
renewed by resending it using the drop-down menu on the tester row.
## Next steps
- Implement [in-app feedback](https://firebase.google.com/docs/app-distribution/collect-feedback-from-testers.md.txt)
to collect feedback from testers about your app (including
screenshots).
- Learn how to display [in-app alerts](https://firebase.google.com/docs/app-distribution/set-up-alerts.md.txt?platform=android)
to your testers when new builds of your app are available to install.
- Visit the [Android App Bundle codelab](https://firebase.google.com/codelabs/appdistribution-app-bundles)
to learn how to distribute app bundle releases step by step.
- Learn best practices for [distributing Android apps to QA testers using CI/CD](https://firebase.google.com/docs/app-distribution/best-practices-distributing-android-apps-to-qa-testers-with-ci-cd.md.txt).