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.

ParameterDescriptionRequired

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.

Sample App Link

<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 that is hosted by 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 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.

MainActivity.java:

@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
                }
            });
    }
}

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