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 build.gradle
file, letting you configure
distributions for different build types and variants of your app.
Before you begin
If you haven't already, add Firebase to your Android project.
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.
1. Set up your Android project
In your module (app-level) Gradle file (usually app/build.gradle
), include the
App Distribution plugin below the Android plugin:
apply plugin: 'com.android.application'
// ...
apply plugin: 'com.google.firebase.appdistribution'
// ...
buildscript {
repositories {
google()
}
dependencies {
classpath 'com.google.firebase:firebase-appdistribution-gradle:1.2.0'
}
}
2. Authenticate with Firebase
Before you can use the Gradle plugin, you must first authenticate with your Firebase project. There are three ways to achieve this:
- Sign in to your Google Account via the Gradle plugin
- Use Firebase service account credentials
- Sign in to Firebase using the Firebase CLI
Authenticate using your Google Account
-
Run the following command:
./gradlew appDistributionLogin
The command prints an authentication link. -
Open the link in a browser.
-
When prompted, sign in to your Google Account and grant permission to access your Firebase project. The Gradle command prints a refresh token, which the App Distribution plugin uses to authenticate with Firebase.
-
Set the environment variable
FIREBASE_TOKEN
to the token from the previous step:export FIREBASE_TOKEN=<token>
Authenticate using a service account
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 ADC configured for another Google service (e.g., Google Cloud Platform).
To authenticate using service account credentials:
- On the Google Cloud Platform console, select your project and create a new service account.
- Add the Firebase Quality Admin role.
- 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 your Firebase project.
- Skip this step if you created your app after September 20, 2019: In the Google APIs console, enable the Firebase App Distribution API. When prompted, select the project with the same name as your Firebase project.
Provide or locate your service account credentials:
- To pass Gradle your service account key, in your
build.gradle
file, set the propertyserviceCredentialsFile
to the private key JSON file. To locate your credentials with ADC, set the environment variable
GOOGLE_APPLICATION_CREDENTIALS
. Replace[PATH]
with the path of the private key JSON file and[FILE_NAME]
with the filename. 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.
- To pass Gradle your service account key, in your
3. Configure your distribution properties
In your
app/build.gradle
file, configure App Distribution by adding at least onefirebaseAppDistribution
section. You can configure App Distribution for both build types and product flavors. For example, to distribute therelease
build to testers:android { // ... buildTypes { release { firebaseAppDistribution { releaseNotesFile="/path/to/releasenotes.txt" testers="ali@example.com, bri@example.com, cal@example.com" } } } // ... }
And to distribute
debug
andrelease
builds in "demo" and "full" product flavors: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 App 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 |
serviceCredentialsFile
|
The path to your service account private key JSON file. Required only if you use service account authentication. |
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).
Groups are specified using 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" |
4. Distribute your app to testers
Finally, to package your test app and invite testers, build the targets
assembleBUILD-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 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
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
Testers who haven't been invited to test the app receive email invitations to get started. Existing testers receive email notifications that a new build is ready to test.
For more information about product flavors, see Configure build variants.