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

1. 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.2" apply false
   
       // Add the dependency for the App Distribution Gradle plugin
       id("com.google.firebase.appdistribution") version "5.0.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.2' apply false
   
       // Add the dependency for the App Distribution Gradle plugin
       id 'com.google.firebase.appdistribution' version '5.0.0' apply false
   }
   

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

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

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

See Log in with the Firebase CLI for instructions on how to authenticate your project.

Step 3. Configure your distribution properties

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::

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

android {

  // ...

  buildTypes {
      getByName("release") {
          firebaseAppDistribution {
              artifactType = "APK"
              releaseNotesFile = "/path/to/releasenotes.txt"
              testers = "[email protected], [email protected], [email protected]"
          }
      }
  }

  // ...
}

android {

  // ...

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

  // ...
}

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:

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

  // ...
}

android {

  // ...

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

  flavorDimensions "version"
  productFlavors {
      demo {
          dimension "version"
          firebaseAppDistribution {
              releaseNotes="Release notes for demo version"
              testers="[email protected]"
          }
      }
      full {
          dimension "version"
          firebaseAppDistribution {
              releaseNotes="Release notes for full version"
              testers="[email protected]"
          }
      }
  }

  // ...
}

Use the following parameters to configure the distribution:

appId="1:1234567890:android:321abc456def7890"

testers="[email protected], [email protected], [email protected]"

testersFile="/path/to/testers.txt"

groups="qa-team, android-testers"

groupsFile="/path/to/tester-groups.txt"

testDevices="model=shiba,version=34,locale=en,orientation=portrait;model=b0q,version=33,locale=en,orientation=portrait"

testDevicesFile="/path/to/testDevices.txt"

testPasswordFile="/path/to/testPassword.txt"

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.

   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
   

2. 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="[email protected], [email protected]"
     ./gradlew appDistributionRemoveTesters
         --projectNumber=<project_number>
         --emails="[email protected], [email protected]"
     

     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 (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

• Implement in-app feedback to make it easy for testers to send feedback about your app (including screenshots).

• Learn how to display in-app alerts to your testers when new builds of your app are available to install.

• Visit the Android App Bundle codelab to learn how to distribute app bundle releases step by step.

• Learn best practices for distributing Android apps to QA testers using CI/CD.