Alert testers about your new app releases with Firebase App Distribution Android SDK - Codelab

1. Overview

c7a9160ef7b184c7.png 22e0b52f771c060d.png

Welcome to the Integrating the Firebase App Distribution SDK in your Android app codelab. In this codelab, you'll add the App Distribution Android SDK to your app in order to display in-app alerts to your testers when new builds are available to download. You'll learn how to use both a basic configuration and a custom configuration to get your testers signed in to receive updates. Then you'll push a new release to App Distribution and trigger a new build alert right in the app.

What you'll learn

  • How to use App Distribution to distribute a pre-release app to testers
  • How to integrate the App Distribution Android SDK into your app
  • How to alert a tester when there is a new pre-release build ready to install
  • How to customize the SDK to fit your testing needs

What you'll need

  • Latest Android Studio version.
  • Sample code.
  • A test device with Android 4.4+ and Google Play services 9.8 or later, or an Emulator with Google Play services 9.8 or later.
  • If using a device, a connection cable.

How will you use this tutorial?

Read through it only Read it and complete the exercises

How would you rate your experience with building Android apps?

Novice Intermediate Proficient

2. Get the sample code

Clone the GitHub repository from the command line.

$ git clone https://github.com/FirebaseExtended/codelab-appdistribution-android.git

If you don't have git installed, you can also download the sample project from its GitHub page or by clicking this link.

3. Import the starter app

From Android Studio, select the codelab-appdistribution-android/start directory ( android_studio_folder.png) from the sample code download (File > Open > .../codelab-appdistribution-android/start).

You should now have the start project open in Android Studio.

4. Create a Firebase console project

Add a new Firebase project

  1. Open the Firebase console.
  2. Select Add Project, and then name your project "Firebase Codelab."

You don't need to enable Google Analytics for this project.

  1. Click Create project.

Add an app to Firebase

Register your app with Firebase. Use "com.google.firebase.appdistributioncodelab" as the package name.

Add google-services.json file to your app

After adding the package name and selecting Register, follow these steps to add google-services.json to your app:

  1. Click Download google-services.json to obtain your Firebase Android config file.
  2. Copy the google-services.json file into the app directory in your project.
  3. After the file is downloaded you can Skip the next steps shown in the console (they've already been done for you in the build-android-start project).

Update Application ID to match your Firebase app

  1. In the left menu (Project Tab), make sure you're on the "Android" View and locate the "Gradle Scripts" tab and open your module (app-level) Gradle file (usually app/build.gradle.kts).
  2. Change the applicationId property to match the application ID of your Firebase app. This should be "com.google.firebase.appdistributioncodelab"

Sync your project with Gradle files

To ensure that all dependencies are available to your app, sync your project with Gradle filesselecting File > Sync Project with Gradle Files from the Android Studio toolbar.

5. Set up in-app new build alerts with the App Distribution Android SDK

In this step, you will add the Firebase App Distribution Android SDK to your app and display in-app alerts to your testers when new builds of your app are available to install. To do this, make sure you've enabled the Firebase App Testers API for your "Firebase Codelab" project (in the Google Cloud Console). You need to sign in with the same account and select the correct project from the drop-down menu at the top.

Configure in-app alerts

The App Distribution Android SDK provides two ways of setting up in-app build alerts for your testers:

  • A basic alert configuration, which comes with a pre-built dialog to display to testers.
  • An advanced alert configuration, which lets you customize your user interface (UI).

We will start with the basic alert configuration. You can use updateIfNewReleaseAvailable to display a pre-built enable alerts dialog to testers who haven't yet enabled alerts, and then check if a new build is available. Testers enable alerts by signing into an account that has access to the app in App Distribution. When called, the method enacts the following sequence:

  1. Checks if a tester enabled alerts. If not, the method displays a pre-built dialog that prompts testers to sign into App Distribution with their Google account.

Enabling alerts is a one-time process on the test device that persists across updates of your app. Alerts remain enabled on the test device until the app is uninstalled or until the signOutTester method is called.

  1. Checks for newly available builds for the tester to install.
  2. Displays a pre-built alert prompting the tester to download the latest release.
  3. Checks the new build type before proceeding with the update:
  4. If the new build is an App Bundle (AAB), redirects the tester to the Play Store to complete the update process.
  5. If the new build is an APK, the SDK downloads the new build in the background and prompts the tester to install the new build when the download completes. The SDK sends download progress notifications to the user using NotificationManager. You can add your own progress indicator by attaching an onProgressUpdate handler to the updateIfNewReleaseAvailable Task.

You can call updateIfNewReleaseAvailable()at any point in your app. For example, you can call updateIfNewReleaseAvailable() during the onResume()method of the MainActivity:

Open MainActivity.kt, and create the onResume() method like this:

MainActivity.kt

override fun onResume() {
    super.onResume()
    checkForUpdate()
}

Now let's implement the checkForUpdate() method.

MainActivity.kt

   private fun checkForUpdate() {
        firebaseAppDistribution.updateIfNewReleaseAvailable()
            .addOnProgressListener { updateProgress ->
                // (Optional) Implement custom progress updates in addition to
                // automatic NotificationManager updates.
            }
            .addOnFailureListener { e ->
                if (e is FirebaseAppDistributionException) {
                    // Handle exception.
                }
            }
    }

6. Build and invite testers to download your app

In this step, you build your app and test your implementation by distributing the build to testers using the Firebase console.

Build your app

When you're ready to distribute a pre-release version of your app to testers, build your APK using your normal process. You must sign the APK with your debug key or app signing key.

Distribute your app to testers

To distribute your app to testers, upload the APK file using the Firebase console:

  1. Open the App Distribution page of the Firebase console. Select your Firebase project when prompted.
  2. On the Releases page, select the app you want to distribute from the drop-down menu.

623460c3c8a82ce6.png

  1. Click Get Started

bf503b25066ff4a4.png

  1. Drag your app's APK file to the console to upload it.
  2. When the upload completes, specify the tester groups and individual testers you want to receive the build. (Add your email to receive the invite.) Then, add release notes for the build. To learn more about creating tester groups, see Add and remove testers.

3343048f0930e84b.png

  1. Click Distribute to make the build available to testers.

2be58fe195928bf9.png

In the Firebase console, you can now see the testers you added under your app's release.

9935a41810344c61.png

Since you included your email address, you'll receive an email from Firebase App Distribution inviting you to test the app. You're now the first tester! Follow the instructions in Accept the invitation to get set up as a tester on your test device.

Accept the invitation

You'll need to first accept the invitation to download and test the release.

  1. On your Android test device, open the email sent from Firebase App Distribution and tap Get Started.
  2. In the Firebase App Distribution tester web app that appears, sign in with your Google account and tap Accept invitation. You can now see the release you're invited to test.

c18cb684f8e82ad6.png

Download the release from the test device

When you navigate to the AppDistribution codelab app, you can see that the release is ready to download.

5414d9a536f25ece.png

  1. Tap Download, then install and run the app!
  2. When the app starts, it asks you to enable new build alerts. Tap Turn on.

b059e09acaa4779f.png

  1. Sign in with your tester account..

22e0b52f771c060d.png

You are returned to the app. The next time you run the app, you don't need to sign in or accept alerts

c9f33df16a2680d.png

Distribute an update to your testers

  1. Update your versionName to "1.1" and versionCode to 2 in your module (app-level) Gradle file (usually app/build.gradle).
  2. Build your APK using your normal process. You must sign the APK with your debug key or app signing key.
  3. Upload this new APK in your Firebase console, add your email as tester again and click Distribute.

2dfa702edfdce6b8.png

Test build alerts

  1. Make sure you closed the app if it was open.
  2. Restart the app.
  3. When the app restarts, you receive a New Version Available alert.

987e3d0ba4e56f84.png

  1. To receive the latest version, click Update.
  2. If prompted, choose the option to enable installs from unknown sources.
  3. Click Install (or Update) on the next screen.

a7c7cd15d60bc764.png

  1. Congratulations! You were able to update your app with the built-in alerts.

7. Customize tester sign-in

The methods signInTester/signOutTester and isTesterSignedIn give you more flexibility customizing your tester's sign-in experience, so it can better match your app's look and feel.

The following example checks whether the tester has already signed into their Firebase App Distribution tester account, so you can choose to display your sign-in UI only for testers who haven't yet signed in. After the tester has signed in, you can then call checkForUpdate to check whether the tester has access to a new build.

Let's disable checking updates automatically in onResume by commenting out checkForUpdate() call.

MainActivity.kt

override fun onResume() {
        super.onResume()
        //checkForupdate()
    }

Instead, checkForUpdate() is already added in updatebutton's OnClickListener.

Now, let's implement our signIn() method which will signIn the user if they are signed out, or sign out the user if they are already signed in.

MainActivity.kt

    private fun signIn() {
        if (isTesterSignedIn()) {
            firebaseAppDistribution.signOutTester()
            configureUpdateButton()
            configureSigninButton()
        } else {
            firebaseAppDistribution.signInTester()
        }
    }

Finally let's implement the isTesterSignedIn method.

MainActivity.kt

    private fun isTesterSignedIn() : Boolean {
        return firebaseAppDistribution.isTesterSignedIn
    }

Build and test your implementation

8. Congratulations!

You have built the "in-app alerts display" feature into an app using Firebase App Distribution Android SDK.

What we've covered

  • Firebase App Distribution
  • Firebase App Distribution New Alerts Android SDK

Next Steps

Learn More

Have a Question?

Report Issues