App Invites for iOS

To send app invites you must use version 4.0 or later of the Facebook SDK for iOS. Read more about getting started with the Facebook SDK for iOS to properly set up your development environment.

You need to be logging the activateApp App Event for accurate installation tracking. Learn more here

Open the Dialog

Open the dialog with the following call:

FBSDKAppInviteContent *content =[[FBSDKAppInviteContent alloc] init];
content.appLinkURL = [NSURL URLWithString:@"https://www.mydomain.com/myapplink"];
//optionally set previewImageURL
content.appInvitePreviewImageURL = [NSURL URLWithString:@"https://www.mydomain.com/my_invite_image.jpg"];

// present the dialog. Assumes self implements protocol `FBSDKAppInviteDialogDelegate`
[FBSDKAppInviteDialog showWithContent:content
                             delegate:self];

Like other dialogs in FBSDKShareKit, you can call canShow on a FBSDKAppInviteDialog beforehand to determine if the dialog is available on the current device.

Dialog Parameters

There are 2 parameters passed to the invite dialog: The App Link URL and preview image URL.

Parameter	Description	Required
App Link URL	App Link for what should be opened when the recipient clicks on the install/play button on the app invite page.	Yes
Preview Image URL	A url to an image to be used in the invite.	No

App Link URL

The App Link URL is a deep link to a specific place in your mobile app. Read more about this in the section on App Links.

Your app link URL must contain the proper data and structure in order for App Invites to function.

Preview Image URL

The preview image URL will be used to render the image in the invite. While not required, it is recommended you pass this field in as your invite may not be rendered if no alternative images are found.in as your invite may not be rendered if no alternative images are found.

If a previewImageURL is not set the invite will use Promotional Images from the App Details section in apps settings. The invite will not show if no images are available.

The suggested image size is 1,200 x 628 pixels with an image ratio of 1.9:1.

App Links

The App Links protocol is a cross-platform, open-source protocol for simple mobile deep-linking. App Invites uses App Links to determine which apps to display on install and what URL to pass to your app. Read more about App Links at applinks.org or read Facebook's guide on App Links.

Sample App Link Markup

<html>
<head>
    <meta property="al:ios:url" content="couchinapp://invite_from_fb?referral=123456789" />
    <meta property="al:ios:app_store_id" content="123456789" />
    <meta property="al:ios:app_name" content="Couchin'" />
    <meta property="al:android:url" content="couchinapp://invite_from_fb?referral=123456789" />
    <meta property="al:android:app_name" content="Couchin" />
    <meta property="al:android:package" content="com.mycompany.couchin" />
    <meta property="al:web:url" content="http://www.couchinapp.com/myapp.html" />
</head>
<body>
    Couchin App Link
</body>
</html>

App Link Tool

You can use our tool to create App Links hosted on Facebook. This is useful if you're a mobile developer and you don't want to host any content on the web.

Create App Link

Support Incoming Links to Your App

When people tap the Open / Play button on the invite or the Is Ready installation notification, they will be taken to your app. The URL defined in the App Link will be passed in. Use URLWithInboundURL from the Bolts framework to obtain this App Link. Read more details about supporting incoming links.

- (BOOL)application:(UIApplication *)application
            openURL:(NSURL *)url
            sourceApplication:(NSString *)sourceApplication
            annotation:(id)annotation {
    BFURL *parsedUrl = [BFURL URLWithInboundURL:url sourceApplication:sourceApplication];
    if ([parsedUrl appLinkData]) {
        NSURL *targetUrl = [parsedUrl targetURL];
        //process applink data
    }
    ...
}

Dynamic App Link endpoint

In order to support advanced deeplinking scenarios you may want to have a contextual App Link for each invite with additional information, such as a referral code. One way to do this is to host a dynamic server endpoint which generates custom App Links based on a URL query strings passed in.

Sample Dynamic App Link

http://couchinapp.com/applink/?referral=123456789

This endpoint would contain server-side logic to return HTML with App Link meta properties. Append any relevant context, like a referral code, to the al:ios:url and al:android:url via URL query strings like the sample app link above. Once inside the app, you can use NSURLComponents.queryItems in iOS8 to parse the referral code, as in the example below.

//Processing App Link data
BFURL *parsedUrl = [BFURL URLWithInboundURL:url sourceApplication:sourceApplication];
if ([parsedUrl appLinkData]) {
    NSURL *targetUrl = [parsedUrl targetURL];  
    NSURLComponents *urlComponents = [NSURLComponents componentsWithURL:targetUrl resolvingAgainstBaseURL:NO];
    NSArray *queryItems = urlComponents.queryItems;
    NSString *refCode = [self valueForKey:@"referral" fromQueryItems:queryItems];
    NSLog(@"Referral Code: %@", refCode);
}

Handling Cold Starts

In rare cases your app could be closed by the operating system while fast app switching. To handle this case add the following code to your app delegate. Adding this code will allow your app to handle people coming back from the invites dialog to your app in a "non-running" state.

AppDelegate.m:

- (BOOL)application:(UIApplication *)application
            openURL:(NSURL *)url
            sourceApplication:(NSString *)sourceApplication
            annotation:(id)annotation {
  return [FBAppCall handleOpenURL:url
                sourceApplication:sourceApplication
                fallbackHandler:^(FBAppCall *call) {
                if ([call.dialogData.method isEqualToString:@"appinvites"]) {
                    // handle response
                }
  }];
}

- (void)applicationDidBecomeActive:(UIApplication *)application {
    [FBAppCall handleDidBecomeActive];
}

Testing

We have internal logic that determines whether a push notification is sent to the client. If we detect that the person has installed the app, we may not trigger a push notification. The best way to test push notifications is to use test users.

Setting an App Category

In order to take advantage of the best ranking for your app, please be sure to set your app's category correctly in App Settings.