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 th 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:

    Objective-C

    @import Firebase;
    

    Swift

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

    Objective-C

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

    Swift

    // Use Firebase library to configure APIs
    FIRApp.configure()
    
  6. 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:(UIApplication *)application
    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  // Use Firebase library to configure APIs
  [FIRApp configure];
  return YES;
}
- (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

func application(application: UIApplication,
  didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool {
  // Use Firebase library to configure APIs
  FIRApp.configure()
  return true
}
@available(iOS 9.0, *)
func application(application: UIApplication, openURL url: NSURL, options: [String : AnyObject])
  -> Bool {
    return self.application(application, openURL: url, sourceApplication: options[UIApplicationOpenURLOptionsSourceApplicationKey] as? String, annotation: "")
}

func application(application: UIApplication,
  openURL url: NSURL, sourceApplication: String?, annotation: AnyObject) -> Bool {
    if let invite = FIRInvites.handleURL(url, sourceApplication:sourceApplication, annotation:annotation) as? FIRReceivedInvite {
      let matchType =
          (invite.matchType == FIRReceivedInviteMatchType.Weak) ? "Weak" : "Strong"
      print("Invite received from: \(sourceApplication) Deeplink: \(invite.deepLink)," +
          "Id: \(invite.inviteId), Type: \(matchType)")
      return true
    }

    return GIDSignIn.sharedInstance().handleURL(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 {
  _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 invation 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 invation 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];
  [[[UIAlertView alloc] initWithTitle:@"Done"
                              message:message
                             delegate:nil
                    cancelButtonTitle:@"OK"
                    otherButtonTitles:nil] show];
}

Swift

func inviteFinishedWithInvitations(invitationIds: [AnyObject], error: NSError?) {
  if let error = error {
    print("Failed: " + error.localizedDescription)
  } else {
    print("Invitations sent")
  }
}

Send feedback about...

Need help? Visit our support page.