firebase invites: send and receive

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:

   SWIFT

   OBJECTIVE-C

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

   SWIFT

   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.

If the Invites SDK indicates a weak match for a deeplink, it means that the match between the deeplink and the receiving device may not be perfect. In this case your app should reveal no personal information from the deeplink.

SWIFT

OBJECTIVE-C

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

- (BOOL)application:(UIApplication *)application
            openURL:(NSURL *)url
  sourceApplication:(NSString *)sourceApplication
         annotation:(id)annotation {
  if ([[GIDSignIn sharedInstance] handleURL:url
                      sourceApplication:sourceApplication
                                 annotation:annotation]) {
    return YES;
  }
  // Handle App Invite requests
  return [FIRInvites handleUniversalLink:url
                              completion:^(FIRReceivedInvite * _Nullable receivedInvite,
                                           NSError * _Nullable error) {
    // ...
  }];
}

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:

SWIFT

OBJECTIVE-C

@interface ViewController ()<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:

SWIFT

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

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.

Method	Channels	Description
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.
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:

SWIFT

OBJECTIVE-C

FIRInvitesTargetApplication *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:

SWIFT

OBJECTIVE-C

- (void)inviteFinishedWithInvitations:(NSArray *)invitationIds error:(NSError *)error {
  if (error) {
    NSLog(@"%@", error.localizedDescription);
  } else {
    NSLog(@"%li invites sent", invitationIds.count);
  }
}