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
Select your project in the Google Cloud Console.
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.
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'
In the directory of your podfile, run
pod install
, then open the created.xcworkspace
file.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 yourInfo.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
Import the Firebase module in your
UIApplicationDelegate
:Swift
import Firebase
Objective-C
@import Firebase;
Configure a
FirebaseApp
shared instance, typically in your app'sapplication:didFinishLaunchingWithOptions:
method:Swift
// Use Firebase library to configure APIs FirebaseApp.configure()
Objective-C
// Use Firebase library to configure APIs [FIRApp configure];
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:
Checks if a tester has enabled alerts by prompting them to sign into App Distribution with their Google account.
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.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:
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).
}];
Display dialogue for installing new build:
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];
}
}];
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