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
- If you haven't yet connected your app to your Firebase project, do so from the Firebase console.
- 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.
- Add Firebase to your iOS
project. Include the following Pod in your
Podfile
:pod 'Firebase/Invites'
- Import the Firebase module:
Objective-C
@import Firebase;
Swift
import Firebase
- Configure a
FIRApp
shared instance, typically in your application'sapplication:didFinishLaunchingWithOptions:
method:Objective-C
// Use Firebase library to configure APIs [FIRApp configure];
Swift
// Use Firebase library to configure APIs FIRApp.configure()
- 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.
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. |
setDescription |
Sets the description of your app that is included in email invitations. Cannot exceed 1000 characters. | |
setCustomImage |
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 |
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") } }