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 fastlane

This guide describes how to distribute AAB builds to testers using fastlane, an open source platform that automates building and releasing iOS and Android apps. It follows simple instructions defined in a Fastfile. After you set up fastlane and your Fastfile, you can integrate App Distribution with your fastlane configuration.

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 fastlane

  1. Install and set up fastlane.

  2. To add App Distribution to your fastlane configuration, run the following command from the root of your Android project:

    fastlane add_plugin firebase_app_distribution

    If the command prompts you with an option, select Option 3: RubyGems.org.

Step 2. Authenticate with Firebase

Before you can use the Fastlane plugin, you must first authenticate with your Firebase project. There are three ways to achieve this:

Step 3. Set up your Fastfile and distribute your app

  1. In a ./fastlane/Fastfile lane, add a firebase_app_distribution block. Use the following parameters to configure the distribution:

    firebase_app_distribution parameters
    app

    Required: Your app's Firebase App ID. You can find the App ID in the Firebase console, on the General Settings page.

    app: "1:1234567890:android:0a1b2c3d4e5f67890"
    firebase_cli_token

    A refresh token that's printed when you run the plugin's login action (see Authenticate using a Google account, above), or when you authenticate your CI environment with the Firebase CLI (read Use the CLI with CI systems for more information).

    service_credentials_file

    The path to your Google service account json file. See above for how to authenticate using service account credentials.

    android_artifact_type

    Specifies the Android file type (APK or AAB).

    android_artifact_path

    Replaces apk_path (deprecated). Absolute path to the APK or AAB file you want to upload. If unspecified, fastlane determines the file's location from the lane in which the file was generated.

    release_notes
    release_notes_file

    Release notes for this build.

    You can either specify the release notes directly:

    release_notes: "Text of release notes"

    Or, specify the path to a plain text file:

    release_notes_file: "/path/to/release-notes.txt"
    testers
    testers_file

    The email addresses of the testers you want to invite.

    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 plain text file containing a comma-separated list of email addresses:

    testers_file: "/path/to/testers.txt"
    groups
    groups_file

    The tester groups you want to invite (refer to Manage testers). Groups are specified using group aliases, which you can look up in the Firebase console.

    You can specify the groups as a comma-separated list:

    groups: "qa-team, trusted-testers"

    Or, you can specify the path to a plain text file containing a comma-separated list of group names:

    groups_file: "/path/to/groups.txt"
    debug

    A boolean flag. You can set this to true to print verbose debug output.

    For example:

    platform :android do
        desc "My awesome app"
        lane :distribute do
            build_android_app(task: "bundle", ...)
            # build_android_app is a built-in fastlane action.
    
            firebase_app_distribution(
                app: "1:123456789:android:abcd1234",
                testers: "tester1@company.com, tester2@company.com",
                release_notes: "Lots of amazing new features to test out!",
                android_artifact_type: "AAB"
            )
    
        end
    end
    
  2. Finally, to make the build available to testers, run your lane:

    fastlane <lane>

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.