With the release of the Facebook SDK version 4.28.0, App Invites is deprecated. It will be supported until February 5, 2018.

App Invites for Android

To send app invites you must use version 4.0 or later of the Facebook Android SDK. Read more about getting started with the Facebook SDK for Android to properly setup for you environment.

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

Open the Dialog

In order to open the dialog, call the following code:

String appLinkUrl, previewImageUrl;

appLinkUrl = "https://www.mydomain.com/myapplink";
previewImageUrl = "https://www.mydomain.com/my_invite_image.jpg";

if (AppInviteDialog.canShow()) {
    AppInviteContent content = new AppInviteContent.Builder()
                .setApplinkUrl(appLinkUrl)
                .setPreviewImageUrl(previewImageUrl)
                .build();
    AppInviteDialog.show(this, content);
}

The call to canShow checks to see whether the dialog can be opened (Facebook native app is installed or the minimum requirements are met for the webview). Data is passed to the builder which will be used in the invite. The call to AppInviteDialog.show shows the dialog.

Dialog parameters

There are 2 parameters passed to the invite dialog: 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 URL to your app link. 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 1.9:1.

The App Links protocol is 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>

When people open your app through the Open / Play button on the invite, the Is Ready installation notification, or the home screen, the URL defined in the App Link will be passed in. Use AppLinks.getTargetUrlFromInboundIntent from the Bolts framework to obtain this App Link. Read more details about support incoming links.

If your application is not launched from an Intent you can fetch a deferred App Link with AppLinkData.fetchDeferredAppLinkData. See an example of this below:

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    ...
    FacebookSdk.sdkInitialize(this);
    Uri targetUrl =
      AppLinks.getTargetUrlFromInboundIntent(this, getIntent());
    if (targetUrl != null) {
        Log.i("Activity", "App Link Target URL: " + targetUrl.toString());
    } else {
        AppLinkData.fetchDeferredAppLinkData(
            activity, 
            new AppLinkData.CompletionHandler() {
                @Override
                public void onDeferredAppLinkDataFetched(AppLinkData appLinkData) {
                    //process applink data
                }
            });
    }
}

Supporting 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 AppInviteContent object, and you must set up your app delegate to receive the promotional code.

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

String appLinkUrl, previewImageUrl;

appLinkUrl = "https://www.mydomain.com/myapplink";
previewImageUrl = "https://www.mydomain.com/my_invite_image.jpg";

if (AppInviteDialog.canShow()) {
    AppInviteContent content = new AppInviteContent.Builder()
                .setApplinkUrl(appLinkUrl)
                .setPreviewImageUrl(previewImageUrl)
                .setPromotionDetails("Example Promotional Message", "EXAMPLEPROMO ")
                .build();
    AppInviteDialog.show(this, content);
}

To retrieve a sent promotional code, set up your activity's onCreate() method as in the Supporting Incoming Links to Your App section above, and in the onDeferredAppLinkDataFetched() method of your CompletionHandler, check whether a promo code was included:

String promoCode = appLinkData.getPromotionCode();
if (promoCode != null) {
  // ... execute code related to the promotion ...
}

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 Uri.getQueryParameter to parse the referral code, as in the example below:

//Processing App Link data
Uri targetUrl =
  AppLinks.getTargetUrlFromInboundIntent(this, getIntent());
if (targetUrl != null) {
  string refCode = targetUrl.getQueryParameter("referral");
  Log.i("Activity", "Referral Code: " + refCode);
} 

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.

Set the 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.