Send and Receive Firebase Invites from Your iOS App

Prerequisites

Firebase Invites requires iOS 8 or newer. You can target iOS 7 in your app, but all Firebase Invites SDK calls will be no-ops if the app isn't running on iOS 8 or newer.

Before you begin

  1. If you haven't yet connected your app to your Firebase project, do so from the Firebase console.
  2. If you haven't yet enabled Firebase Dynamic Links, do so from the Firebase console by opening the Dynamic Links section and accepting the terms of service if prompted. Because Firebase Invites is built on Firebase Dynamic Links, you must enable Firebase Dynamic Links to use Firebase Invites.
  3. Add Firebase to your iOS project. Include the following Pod in your Podfile:
    pod 'Firebase/Invites'
  4. Import the Firebase module in your UIApplicationDelegate subclass:

    Swift

    import Firebase
    

    Objective-C

    @import Firebase;
    
  5. Configure a FIRApp shared instance, typically in your application's application:didFinishLaunchingWithOptions: method:

    Swift

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

    Objective-C

    // Use Firebase library to configure APIs
    [FIRApp configure];
    
  6. In Xcode, edit your project's Info.plist and add a property with the key NSContactsUsageDescription ("Privacy - Contacts Usage Description") and a value that describes how your app uses contacts data. For example: "MyRecipeApp uses your contacts to make it easy to share recipes with your friends."
  7. Implement Google Sign-In in your app. Users must be signed in with their Google Accounts to send invitations.

Handle incoming app invites

After you have configured your app, you must next enable your app to handle incoming app invites.

When a user selects an incoming app invite on their iOS device, if the user has not yet installed your app, they can choose to install your app from its iTunes App Store page. When the user opens your app for the first time, it's important for your app to provide a personalized onboarding experience to increase the likelihood they will become an engaged, long-term user of your app. To help you do this, the Invites SDK provides the deeplink and invitation ID associated with the app invite received by the user.

Objective-C

- (BOOL)application:(nonnull UIApplication *)application
            openURL:(nonnull NSURL *)url
            options:(nonnull NSDictionary<NSString *, id> *)options {
  return [self application:application
                   openURL:url
         sourceApplication:options[UIApplicationOpenURLOptionsSourceApplicationKey]
                annotation:options[UIApplicationOpenURLOptionsAnnotationKey]];
}

- (BOOL)application:(UIApplication *)application
            openURL:(NSURL *)url
  sourceApplication:(NSString *)sourceApplication
         annotation:(id)annotation {
  // Handle App Invite requests
  FIRReceivedInvite *invite =
      [FIRInvites handleURL:url sourceApplication:sourceApplication annotation:annotation];
  if (invite) {
    NSString *matchType =
        (invite.matchType == FIRReceivedInviteMatchTypeWeak) ? @"Weak" : @"Strong";
    NSString *message =
        [NSString stringWithFormat:@"Deep link from %@ \nInvite ID: %@\nApp URL: %@\nMatch Type:%@",
                                   sourceApplication, invite.inviteId, invite.deepLink, matchType];

    [[[UIAlertView alloc] initWithTitle:@"Deep-link Data"
                                message:message
                               delegate:nil
                      cancelButtonTitle:@"OK"
                      otherButtonTitles:nil] show];

    return YES;
  }

  return [[GIDSignIn sharedInstance] handleURL:url
                             sourceApplication:sourceApplication
                                    annotation:annotation];
}

Swift

@available(iOS 9.0, *)
func application(_ application: UIApplication, open url: URL, options: [UIApplicationOpenURLOptionsKey : Any])
  -> Bool {
    return self.application(application, open: url, sourceApplication: options[UIApplicationOpenURLOptionsKey.sourceApplication] as? String, annotation: "")
}

func application(_ application: UIApplication,
  open url: URL, sourceApplication: String?, annotation: Any) -> Bool {
    if let invite = FIRInvites.handle(url, sourceApplication:sourceApplication, annotation:annotation) as? FIRReceivedInvite {
      let matchType =
          (invite.matchType == .weak) ? "Weak" : "Strong"
      print("Invite received from: \(sourceApplication) Deeplink: \(invite.deepLink)," +
          "Id: \(invite.inviteId), Type: \(matchType)")
      return true
    }

    return GIDSignIn.sharedInstance().handle(url, sourceApplication: sourceApplication, annotation: annotation)
}

Enable your users to send app invites

Now that your app is ready to handle incoming invites correctly, it is time to enable your app to send invitations to the user's contacts.

Before a user can send Invites, the user must be signed in with their Google Account.

To send invitations, first declare that you are implementing the FIRInviteDelegate protocol:

Objective-C

@interface ViewController ()<FIRInviteDelegate>

Swift

class ViewController: UIViewController, FIRInviteDelegate {
  // ...

Then, add Send Invitation buttons to your app. You can add this button as an option in your main menu, or add this button alongside your deep-linkable content, so that users can send specific content along with the invitation. See the Firebase Invites best practices.

When users tap your Send Invitation button, open the invitation dialog:

Objective-C

- (IBAction)inviteTapped:(id)sender {
  id<FIRInviteBuilder> inviteDialog = [FIRInvites inviteDialog];
  [inviteDialog setInviteDelegate:self];

  // NOTE: You must have the App Store ID set in your developer console project
  // in order for invitations to successfully be sent.
  NSString *message =
      [NSString stringWithFormat:@"Try this out!\n -%@",
                                 [GIDSignIn sharedInstance].currentUser.profile.name];

  // A message hint for the dialog. Note this manifests differently depending on the
  // received invitation type. For example, in an email invite this appears as the subject.
  [inviteDialog setMessage:message];

  // Title for the dialog, this is what the user sees before sending the invites.
  [inviteDialog setTitle:@"Invites Example"];
  [inviteDialog setDeepLink:@"app_url"];
  [inviteDialog setCallToActionText:@"Install!"];
  [inviteDialog setCustomImage:@"https://www.google.com/images/branding/googlelogo/2x/googlelogo_color_272x92dp.png"];
  [inviteDialog open];
}

Swift

@IBAction func inviteTapped(_ sender: AnyObject) {
  if let invite = FIRInvites.inviteDialog() {
    invite.setInviteDelegate(self)

    // NOTE: You must have the App Store ID set in your developer console project
    // in order for invitations to successfully be sent.

    // A message hint for the dialog. Note this manifests differently depending on the
    // received invitation type. For example, in an email invite this appears as the subject.
    invite.setMessage("Try this out!\n -\(GIDSignIn.sharedInstance().currentUser.profile.name)")
    // Title for the dialog, this is what the user sees before sending the invites.
    invite.setTitle("Invites Example")
    invite.setDeepLink("app_url")
    invite.setCallToActionText("Install!")
    invite.setCustomImage("https://www.google.com/images/branding/googlelogo/2x/googlelogo_color_272x92dp.png")
    invite.open()
  }
}

Customize the invitation

When you create the invitation dialog, you must specify the title of the invitation dialog and the invitation message to send. You can also customize the image and deep link URL that get sent in the invitation, as in the example above.

MethodChannelsDescription
setTitle Email & SMS Required: Sets the title of the invitation dialog.
setMessage Email & SMS Required: Sets the default text of SMS invitations and the default subject of email invitations. This message can be edited by the sender in the invitation dialog. Cannot exceed 100 characters.
setDeepLink Email & SMS Sets the link into your app that is sent with invitations. Specify this to share specific content with the recipient, or to otherwise present a custom experience when a user opens your app from an invitation.
setDescription Email Sets the description of your app that is included in email invitations. Cannot exceed 1000 characters.
setCustomImage Email Sets the URL of a custom image to include in email invitations. The image must be square and around 600x600 pixels. The image can be no larger than 4000x4000 pixels.
setCallToActionText Email Sets the call-to-action text of the button rendered in email invitations. Cannot exceed 32 characters.

If you have an Android version of your app and you want to send an invitation that can be opened on Android in addition to iOS, call setOtherPlatformsTargetApplication:targetApplication before you open the invitation. For example:

Objective-C

FIRInvitesTargetApplication *targetApplication = [[FIRInvitesTargetApplication alloc] init];
targetApplication.androidClientID = self.androidClientIDLabel.text;
[inviteBuilder setOtherPlatformsTargetApplication:targetApplication];

Swift

let targetApplication = FIRInvitesTargetApplication.alloc().init()
targetApplication.androidClientID = self.androidClientIDLabel.text
inviteBuilder.setOtherPlatformsTargetApplication(targetApplication)

The inviteTapped method then opens the contact chooser dialog where the user selects the contacts to invite. Invitations are sent by email or SMS. After the user sends the invitation, your app receives a callback to the inviteFinishedWithInvitations method:

Objective-C

- (void)inviteFinishedWithInvitations:(NSArray *)invitationIds error:(NSError *)error {
  NSString *message =
      error ? error.localizedDescription
            : [NSString stringWithFormat:@"%lu invites sent", (unsigned long)invitationIds.count];

  if ([UIAlertController class]) {
    UIAlertAction *okAction = [UIAlertAction actionWithTitle:@"OK"
                                                       style:UIAlertActionStyleDefault
                                                     handler:^(UIAlertAction *action) {
                                                       NSLog(@"OK");
                                                     }];

    UIAlertController *alertController = [UIAlertController alertControllerWithTitle:@"Done"
                                                                             message:message
                                                                      preferredStyle:UIAlertControllerStyleAlert];
    [alertController addAction:okAction];
    [self presentViewController:alertController
                       animated:YES
                     completion:nil];
  } else {
    [[[UIAlertView alloc] initWithTitle:@"Done"
                                message:message
                               delegate:nil
                      cancelButtonTitle:@"OK"
                      otherButtonTitles:nil] show];
  }
}

Swift

func inviteFinished(withInvitations invitationIds: [Any], error: Error?) {
  if let error = error {
    print("Failed: " + error.localizedDescription)
  } else {
    print("Invitations sent")
  }
}

Send feedback about...

Need help? Visit our support page.