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

The optional Firebase App Distribution SDK lets you display in-app alerts to your testers when new builds of your app are available to install. This guide explains how to use the App Distribution SDK to create and customize new build alerts for your testers.

Before you begin

If you haven't already, add Firebase to your iOS project.

Step 1: Enable the App Distribution Tester API

1. Select your project in the Google Cloud Console.

2. Under Firebase App Testers API, click Enable.

Step 2: Add App Distribution to your app

We recommend using CocoaPods to install the Firebase libraries. You can also choose to integrate the SDK frameworks directly.

1. Open the podfile you created for the project (or run pod init to create one), then add the following line inside the target section:

   pod 'Firebase/AppDistribution'

2. In the directory of your podfile, run pod install, then open the created .xcworkspace file.

3. Encode your Google app ID (required only for iOS versions 9 and 10):

   Encode your Google app ID

   Add the appdistribution-<encoded-google-app-id> URL scheme by including the snippet in your Info.plist file (refer to Apple's documentation for instructions on how to add the URL scheme in Xcode):

   <key>CFBundleURLTypes</key>
   <array>
       <dict>
           <key>CFBundleTypeRole</key>
           <string>Editor</string>
           <key>CFBundleURLSchemes</key>
           <array>
               <string>appdistribution-<encoded-google-app-id></string>
           </array>
       </dict>
   </array>
   

   Then, encode your Google app ID by replacing the colons (:) with dashes (-). Note that your Google app ID is located in your GoogleService-Info.plist file. For example, if your Google app ID is:

   7:77777777777:ios:123456789

   Your encoded Google app ID is:

   7-77777777777-ios-123456789

4. Import the Firebase module in your UIApplicationDelegate:

   Swift

   import Firebase
   

   Objective-C

   @import Firebase;
   

5. Configure a FirebaseApp shared instance, typically in your app's application:didFinishLaunchingWithOptions: method:

   Swift

   // Use Firebase library to configure APIs
   FirebaseApp.configure()
   

   Objective-C

   // Use Firebase library to configure APIs
   [FIRApp configure];
   

6. Finally, recompile your app.

Step 3: Configure in-app alerts

The App Distribution SDK provides two ways of setting up in-app build alerts for your testers: a basic alert configuration, which comes with a pre-built sign-in dialogue to display to testers, and an advanced alert configuration, which allows you to customize your own user interface (UI). We recommend first using the basic alert configuration if you're new to the App Distribution SDK.

Basic configuration

Use checkForUpdate to display a pre-built enable alerts dialogue to testers who haven't yet enabled alerts, and then check if a new build is available. When called, the method enacts the following sequence:

1. Checks if a tester has enabled alerts by prompting them to sign into App Distribution with their Google account.

2. If the tester has not yet enabled alerts, displays a pre-built dialogue.

   Enabling alerts is a one-time process on the test device and persists across updates of your app. Alerts remain enabled on the test device until either the app is uninstalled, or until the signOutTester method is called. See the method's reference documentation (Swift or Objective-C) for more information.

3. Checks for newly available builds for the tester to install.

You can include checkForUpdate at any point in your app. For example, you can prompt your testers to install newly available builds at startup by including checkForUpdate in the viewDidAppear of the UIViewController.

The following examples check whether or not the tester has enabled alerts and has access to a new build, and if so, displays a dialogue when the build is available to install:

Check for enabled alerts:

AppDistribution.appDistribution().checkForUpdate(completion: { release, error in
// Includes a pre-built enable alerts dialogue that lets your tester enable alerts.
// You can also customize your own user interface that prompts the tester to
// install a newly available distribution (refer to sample code below).
})

[[FIRAppDistribution appDistribution]
    checkForUpdateWithCompletion:^(FIRAppDistributionRelease *_Nullable release,
                                   NSError *_Nullable error) {
// Includes a pre-built enable alerts dialogue that lets your tester enable alerts.
// You can also customize your own user interface that prompts the tester to
// install a newly available distribution (refer to sample code below).
}];

Display dialogue for installing new build:

AppDistribution.appDistribution().checkForUpdate(completion: { release, error in
  guard let release = release else {
    return
  }

  // Customize your alerts here.
  let title = "New Version Available"
  let message = "Version \(release.displayVersion)(\(release.buildVersion)) is available."
  let uialert = UIAlertController(title: title,message: message, preferredStyle: .alert)

  uialert.addAction(UIAlertAction(title: "Update", style: UIAlertAction.Style.default) {
    _ in
    UIApplication.shared.open(release.downloadURL)
  })
  uialert.addAction(UIAlertAction(title: "Cancel", style: UIAlertAction.Style.cancel) {
    _ in
  })

  // self should be a UIViewController.
  self.present(uialert, animated: true, completion: nil)
})

[[FIRAppDistribution appDistribution]
  checkForUpdateWithCompletion:^(FIRAppDistributionRelease *_Nullable release,
                                 NSError *_Nullable error) {
  if (error) {
  UIAlertController *alert = [UIAlertController alertControllerWithTitle:@"Check For Update"
message:[NSString stringWithFormat:@"Error during tester sign in! %@", error.localizedDescription]
preferredStyle:UIAlertControllerStyleAlert];

  UIAlertAction *okAction = [UIAlertAction actionWithTitle:@"Ok" style:UIAlertActionStyleDefault
handler:^(UIAlertAction *action) {}];

  [alert addAction:okAction];
  [self presentViewController:alert animated:YES completion:nil];

  return;
  }

  if (release) {
  UIAlertController *alert = [UIAlertController alertControllerWithTitle:@"New Version Available"
message:[NSString stringWithFormat:@"Version %@ (%@) is available.", release.displayVersion,
release.buildVersion] preferredStyle:UIAlertControllerStyleAlert];

  UIAlertAction *updateAction = [UIAlertAction actionWithTitle:@"Update"
style:UIAlertActionStyleDefault handler:^(UIAlertAction *action) {
    [[UIApplication sharedApplication] openURL:release.downloadURL options:@{}
completionHandler:nil];
  }];
  UIAlertAction *cancelAction = [UIAlertAction actionWithTitle:@"Cancel"
style:UIAlertActionStyleCancel handler:^(UIAlertAction *action) {}];
  [alert addAction:updateAction];
  [alert addAction:cancelAction];
  [self presentViewController:alert animated:YES completion:nil];
  }
}];

Advanced configuration

The methods signInTester 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.

// Sign in a tester without automatically checking for update
if (!AppDistribution.appDistribution().isTesterSignedIn) {
  AppDistribution.appDistribution().signInTester (completion: { error in
    // completion block for signInTester
     if (error != nil) {
       // handle failed sign in
      return
     }
    // handle successful sign in
  })
}

// Only check for update if tester is already signed in - do not prompt
if (AppDistribution.appDistribution().isTesterSignedIn) {
  AppDistribution.appDistribution().checkForUpdate(completion: { release, error in
      // completion block for check for update
  })
}

// Sign in a tester without automatically checking for update
if(![[FIRAppDistribution appDistribution] isTesterSignedIn]) {
  [[FIRAppDistribution appDistribution]
    signInTesterWithCompletion:^(NSError *_Nullable error) {
      // completion block for signInTester
     if (error) {
       // handle failed sign in
       return;
     }
      // handle successful sign in
  }];
}

// only check for update if tester is already signed in - do not prompt
if([[FIRAppDistribution appDistribution] isTesterSignedIn]) {
  [[FIRAppDistribution appDistribution]
        checkForUpdateWithCompletion:^(FIRAppDistributionRelease *_Nullable release,
                                       NSError *_Nullable error) {
     // completion block for check for update
  }];
}

For information on additional methods, including signOutTester, see the App Distribution reference documentation for Swift and Objective-C.

Step 4: Build and test your implementation

Finally, build your app and test your implementation by distributing the build to testers using the Firebase console.

Visit the App Distribution Troubleshooting guide for help with common issues, such as:

• Tester not receiving in-app alerts
• Tester being prompted to sign in to Google more than once