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.
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. Distributing AABs lets you do the following:
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.
Required permissions
To upload AABs to App Distribution, you must
link your Firebase app to an app
in Google Play
. You must have the required level of access
to perform these actions.
If you don't have the necessary Firebase access, you can ask a Firebase project
Owner to assign you the applicable role via the
Firebase console IAM settings
.
If you have questions about accessing your Firebase project, including
finding or assigning an Owner, review the
"Permissions and access to Firebase projects" FAQs
.
The following table applies to linking a Firebase app to an app in
Google Play, as well as uploading AABs.
Action in Firebase console
|
Required IAM permission
|
IAM role(s) that include required permissions by
default
|
Additional required role(s)
|
Link a Firebase app to an app in Google Play
|
firebase.playLinks.update
|
One of the following roles:
|
Access to a Google Play developer account as
Admin
|
Upload AABs to App Distribution
|
firebaseappdistro.releases.update
|
One of the following roles:
|
??
|
Before you begin
If you haven't already,
add Firebase to your Android
project
. At the end of this workflow, you'll
have a Firebase Android App in your Firebase project.
If you aren't using any other Firebase products, you only need to create a
project and register your app. If you decide to use additional
products, be sure to complete all of the steps in
Add Firebase to your Android project
.
To create a Firebase link to Google Play and to upload AABs, make sure that
your app meets the following requirements:
The app in Google Play and the Firebase Android app are both registered
using the same package name.
The app in Google Play is
set up on the app
dashboard
and is distributed to one of the Google Play tracks (Internal testing,
Closed testing, Open testing, or Production).
The app's review in Google Play is complete and the app is published.
Your app is published if the
App status
column displays one of the
following statuses: Internal testing (not Draft internal testing),
Closed testing, Open testing, or Production.
Link your Firebase Android App to your Google Play developer account:
In the Firebase console, go to your
settings
Project settings
,
then select the
Integrations
tab.
On the
Google Play
card, click
Link
.
If you already have links to Google Play, click
Manage
instead.
Follow the on-screen instructions to enable the App Distribution
integration and select which Firebase Android Apps to link to Google
Play.
Learn more about
linking to Google Play
.
Step 1. Set up fastlane
Install and set up fastlane
.
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 in one of the following ways. By default, the fastlane 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 the
firebase_app_distribution
action. 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).
- 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 your service account key to your lane's
firebase_app_distribution
action, set the
service_credentials_file
parameter with the path to your 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.
Step 3. Set up your Fastfile and distribute your app
- 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 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"
|
test_devices
test_devices_file
|
The following distribution types are part of the
Automated tester beta feature
.
The test devices you want to distribute builds to (refer to
Automated tests
).
You can specify the test devices as a semicolon-separated list of test
devices:
test_devices: "model=shiba,version=34,locale=en,orientation=portrait;model=b0q,version=33,locale=en,orientation=portrait"
Or, you can specify the path to a plain text file containing a
semicolon-separated list of test devices:
test_devices_file: "/path/to/test-devices.txt"
|
test_username
|
The username for automatic login to be used during
automated tests
.
|
test_password
test_password_file
|
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:
test_password_file: "/path/to/test-password.txt"
|
test_username_resource
|
Resource name for the username field for automatic login to be used during
automated tests
.
|
test_password_resource
|
Resource name for the password field for automatic login to be used during
automated tests
.
|
test_non_blocking
|
Run
automated tests
asynchronously. Visit the Firebase console for the automatic test results.
|
debug
|
A boolean flag. You can set this to
true
to print verbose debug output.
|
platform :android do
desc "My awesome app"
lane :distribute do
build_android_app(task: "bundle", ...)
# build_android_app is a built-in
fastlane action.
release = 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
To make the build available to testers, run your lane:
fastlane <lane>
The return value of the action is a hash representing the uploaded release.
This hash is also available using
lane_context[SharedValues::FIREBASE_APP_DISTRO_RELEASE]
.
For more information about the available fields in this hash, see the
REST API documentation
.
The fastlane 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:
- A link to the Firebase console displaying a
single release. You can share this link with other developers in your
org.
- 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.
- A signed link that directly downloads and
installs the app binary (APK or AAB file). The link expires after one
hour.
After you distribute your build, it is available in the
App Distribution dashboard of the Firebase console for 150 days.
When the build is 30 days from expiring, an expiration notice appears in
the console and in the tester's list of builds on their test device.
Testers who weren't previously invited to test the app receive email
invitations to get started. Existing testers receive email notifications
that a new build is ready to test. To learn how to install the test app,
see
tester set up guide
. You can monitor
the status of each tester to determine whether they accepted the
invitation and whether they downloaded the app in the
Firebase console.
(Optional) To automatically increment your build number every time you create
a new release in App Distribution, you can use the
firebase_app_distribution_get_latest_release
action
and, for example, the
increment_version_code
fastlane plugin
.
The following code provides an example of how to automatically increment your
build number:
lane :increment_version do
latest_release = firebase_app_distribution_get_latest_release(
app: "<your Firebase app ID>"
)
increment_version_code({ version_code: latest_release[:buildVersion].to_i + 1 })
end
To learn more about the
firebase_app_distribution_get_latest_release
action,
see
Get information about your app's latest release
.
Step 4 (Optional). Managing testers for the distribution
You can add and remove testers from your project or group using your
Fastfile
file or by directly running fastlane actions. Running actions directly
overrides the values set in your
Fastfile
.
Once a tester is added to your Firebase project, you can add them to
individual releases. Testers who are removed from your Firebase project no
longer have access to releases in your project, but they might retain access
to your releases for a window of time.
If you have a large number of testers you should consider using groups.
Use
Fastfile
# Use lanes to add or remove testers from a project.
lane(:add_testers) do
firebase_app_distribution_add_testers(
emails: "foo@google.com,bar@google.com"
# or file: "/path/to/testers.txt"
group_alias: "qa-team" # (Optional) add testers to this group
)
end
lane(:remove_testers) do
firebase_app_distribution_remove_testers(
emails: "foo@google.com,bar@google.com"
# or file: "/path/to/testers.txt"
group_alias: "qa-team" # (Optional) remove testers from this group only
)
end
# Add or remove testers with the terminal
$ fastlane add_testers
$ fastlane remove_testers
Run fastlane actions
fastlane run firebase_app_distribution_create_group display_name:"QA Team" alias:"qa-team"
fastlane run firebase_app_distribution_add_testers group_alias:"qa-team" emails:"foo@google.com,bar@google.com"
fastlane run firebase_app_distribution_remove_testers group_alias:"qa-team" emails:"foo@google.com,bar@google.com"
fastlane run firebase_app_distribution_delete_group alias:"qa-team"
You can also specify testers using
--file="/path/to/testers.txt
instead of
--emails
.
The
firebase_app_distribution_add_testers
and
firebase_app_distribution_remove_testers
tasks also accept the following
arguments:
project_name
: Your Firebase project number.
group_alias
(optional): If specified, the testers are added to (or removed from)
specified group.
service_credentials_file
: The path to your Google service credentials file.
firebase_cli_token
: Auth token for Firebase CLI.
The
service_credentials_file
and the
firebase_cli_token
are the same
arguments used by the upload action.
Step 5 (Optional). Get information about your app's latest release
You can use the
firebase_app_distribution_get_latest_release
action
to fetch information about your app's latest release in App Distribution,
including app version information, release notes, and creation time. Use cases
include automatically increasing the version and carrying over the release
notes from the previous release.
The return value of the action is a hash representing the latest release.
This hash is also available using
lane_context[SharedValues::FIREBASE_APP_DISTRO_LATEST_RELEASE]
.
For more information about the available fields in this hash, see the
REST API documentation
.
Parameters
firebase_app_distribution_get_latest_release 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 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
.
|
debug
|
A boolean flag. You can set this to
true
to print verbose debug output.
|
Next steps