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 is a view controller
// which implements the protocol `FBSDKAppInviteDialogDelegate`.
[FBSDKAppInviteDialog showFromViewController:self
                                 withContent: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

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.

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.

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.

The following is an example of 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

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 {
    BOOL handled = [[FBSDKApplicationDelegate sharedInstance] application:application
        openURL:url
        sourceApplication:sourceApplication
        annotation:annotation
      ];

    if (handled) {
      return handled;
    }

    // If the SDK did not handle the incoming URL, check it for app link data
    BFURL *parsedUrl = [BFURL URLWithInboundURL:url sourceApplication:sourceApplication];
    if ([parsedUrl appLinkData]) {
      NSURL *targetUrl = [parsedUrl targetURL];

      // ...process app link data...

      return YES;
    }

    // ...add any other custom processing...

    return YES;
}

In the sample implementation of -application:openURL:sourceApplication:annotation: above, the call to FBSDKApplicationDelegate is required for deferred deep linking to work correctly. For more information, see the Getting Started documentation for the iOS SDK.

Support Promotional Codes

You may, optionally, send a promotional code with the App Invite. To do so, you must add the promo code and a related message to your FBSDKAppInviteContent object, and you must set up your app delegate to receive the promotional code.

To start, just set up your FBSDKAppInviteContent object as described in the Open the Dialog section above, and then specify your promo code and promo message:

content.promotionCode = @"EXAMPLEPROMO";
content.promotionText = @"Example Promotional Message";

To retrieve a sent promotional code when the App Invite receiver opens the app, set up your -application:openURL:sourceApplication:annotation: method in your app delegate as in the Support Incoming Links to Your App section above. Retrieve the promo code from the incoming URL using FBSDKAppLinkUtility:

  NSString *promoCode = [FBSDKAppLinkUtility appInvitePromotionCodeFromURL:url];

Dynamic App Link Endpoint

In order to support advanced deep-linking 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. The following is an example of a 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 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);
}

Testing

Test App Invites by checking for Facebook notifications. Under certain circumstances, App Invites also sends a push notification, but this is never guaranteed.

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.