Google is committed to advancing racial equity for Black communities. See how.

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

The Firebase App Distribution SDK, which is optional to use, 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 Platform 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. However, if you'd rather not use CocoaPods, you can 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). If you're new to using the SDK, we recommend first trying the basic alert configuration.

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. Once enabled, alerts remain enabled on the device until either the app is uninstalled, or until the signOutTester method is called (for more information on this advanced configuration method, see the App Distribution reference documentation for Swift and Objective-C).

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

For example, the following code checks that the tester has alerts enabled and has access to a new build:

Swift

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

Objective-C

[[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).
}];

Note that you can include this method 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 example displays a dialogue to the tester when a new build is available to install:

Swift

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

Objective-C

[[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];
  }
}];

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

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.

Swift

// 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
  })
}

Objective-C

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