Check out what’s new from Firebase@ Google I/O 2021, and join our alpha program for early access to the new Remote Config personalization feature. Learn more

Distribute Android apps to testers using Gradle

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.

This guide describes how to distribute Android App Bundles (AABs) to testers using the App Distribution Gradle plugin. To follow this guide, you'll need to have access to a Google Play account for which you're an Admin or Owner, and an app that's been published on the Play account.

About distributing Android App Bundles

App Distribution integrates with Google Play’s internal app sharing service to process the AABs you upload and serve APKs that are optimized for your testers' device configurations. When you distribute AABs, you can:

  • Run optimized APKs (served by Google Play) that are optimized to your testers' devices.
  • Uncover and debug device-specific issues.
  • Test app bundle features like Play Feature Delivery and Play Asset Delivery
  • Reduce the size of downloads for your testers.

Before you begin

  1. 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.

  2. Connect your Firebase project to your Google Play account. Once connected, apps that meet the following requirements are automatically linked between your Firebase project and your Google Play account:

    • The app you upload to Google Play and Firebase must share the same package name.

    • The app in Google Play must be in a published state. An app is published when its app store listing has been completed and approved, and the app has been distributed to a following Google Play track: internal, closed, production, or open-testing.

    To connect your Firebase project:

    1. Make sure you are the Owner of your Firebase project and the account Admin or Owner of your Google Play account.

    2. In your Firebase project, navigate to (Settings), then click Project settings > Integrations.

    3. If you haven't already, enable Google Analytics via the Google Analytics card. This is required for linking your project to Google Play.

    4. Click Link on the Google Play card.

Step 1. Set up your Android project

  1. In your project-level Gradle file (usually android/build.gradle), add the App Distribution plugin as a buildscript dependency:

    buildscript {
        repositories {
            // Check that you have Google's Maven repository (if not, add it).
            google()
            jcenter()
        }
        dependencies {
            // Add the App Distribution Gradle plugin
            classpath 'com.google.firebase:firebase-appdistribution-gradle:2.1.2'
        }
    }
    
  2. In your app-level Gradle file (usually android/app/build.gradle), include the App Distribution plugin below the Android plugin:

    apply plugin: 'com.android.application'
    // ...
    
    // Apply the App Distribution Gradle plugin
    apply plugin: 'com.google.firebase.appdistribution'
    // ...
    
  3. 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. There are three ways to achieve this:

Step 3. Configure your distribution properties

In your app/build.gradle file, configure App Distribution by adding at least one firebaseAppDistribution section. For example, to distribute the release build to testers:

```
android {

    // ...

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

    // ...
}
```

You can also override the values set in your build.gradle file by passing command line arguments in the form of -PappDistribution-<property-name>=<property-value>. For example:

./gradlew bundleDebug appDistributionUploadDebug
    -PappDistribution-artifactType="AAB"

App Distribution can be configured for build types and product flavors. For example, to distribute debug and release 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 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".

apkPath

This parameter is now deprecated. Use artifactPath instead.

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"
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 bundleBUILD-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.

For example, to distribute your app using the release build variant, run the following command:

./gradlew bundleRelease 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 bundleRelease appDistributionUploadRelease

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.