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
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.
Step 1. Set up your Android project
In your
root-level (project-level)
Gradle file
(
<project>/build.gradle.kts
or
<project>/build.gradle
), add the
App Distribution Gradle plugin as a dependency:
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.4.1" apply false
// Add the dependency for the App Distribution Gradle plugin
id("com.google.firebase.appdistribution") version "4.2.0" apply false
}
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.4.1' apply false
// Add the dependency for the App Distribution Gradle plugin
id 'com.google.firebase.appdistribution' version '4.2.0' apply false
}
In your
module (app-level)
Gradle file (usually
<project>/<app-module>/build.gradle.kts
or
<project>/<app-module>/build.gradle
),
add the App Distribution Gradle plugin:
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'
}
If you're behind a corporate proxy or firewall, add the following
Java system property
that enables App Distribution to upload your distributions to Firebase:
-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:
- On the
Google Cloud console,
select your project and create a new service account.
- Add the
Firebase App Distribution 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 App Distribution in 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 property
serviceCredentialsFile
to the private key JSON
file.
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.
In your
module (app-level)
Gradle file (usually
<project>/<app-module>/build.gradle.kts
or
<project>/<app-module>/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
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
.
For example, to distribute
debug
and
release
builds in "demo" and "full"
product flavors, follow these instructions:
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
. 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
).
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 following distribution types are part of the
Automated tester beta feature
.
The test devices you want to distribute builds to (see
Automated tests
).
You can specify the test devices as a semicolon-separated list of
device specifications:
testDevices="model=shiba,version=34,locale=en,orientation=portrait;model=b0q,version=33,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
automated tests
.
|
testPassword
or
testPasswordFile
|
The password for automatic login to be used during
automated 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
automated tests
.
|
testPasswordResource
|
Resource name for the password field for automatic login to be used during
automated tests
.
|
testNonBlocking
|
Run
automated tests
asynchronously. Visit the Firebase console for the automatic test results.
|
stacktrace
|
Prints out the stacktrace for user exceptions. This is helpful when
debugging issues.
|
Step 4. Distribute your app to testers
Finally, to package your test app and invite testers, build the targets
BUILD-VARIANT
and
appDistributionUpload
BUILD-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
.
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
You can also override the values set in your
build.gradle
file by passing
command line arguments in the form of
--<property-name>=<property-value>
. For example:
To upload a debug build to App Distribution:
./gradlew bundleDebug appDistributionUploadDebug
--artifactType="APK"
To invite additional testers or remove existing testers from your Firebase
project:
./gradlew appDistributionAddTesters
--projectNumber=<project_number>
--emails="anothertester@email.com, moretesters@email.com"
./gradlew appDistributionRemoveTesters
--projectNumber=<project_number>
--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:
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
(Android native 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
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