App Links on iOS

Your app can post stories to Feed. When people click on those stories, Facebook can send people to either your app or your app's App Store page. This drives traffic and app installs. You can implement this behavior using App Links.

When someone taps on one of the links shared through your app or on the story attribution (name of your app) in one of the Open Graph stories shared through your app, the link content appears in a webview with a menu item Open in {app name}. Clicking on that menu item will either open your app or, if the your app is not installed on the device, open your app's App Store page. If your app is mobile-only and has no web content, when someone clicks the shared link they either open your app, if it's installed, or go to your app's App Store page (if your app isn't installed). The image below shows this flow:

Beginning with iOS v10, deferred deep linking is not supported on devices where the limit ad tracking setting is enabled. On those devices your app can only open the start screen for your app after someone installed your app.

In the following sections we will explain how to handle incoming links once you've set up your App Links.

Handling Incoming Links

When someone taps a link posted from your app or taps the app attribution in an Open Graph story posted from your app in Facebook for iOS, they may be presented with the option to open your content in your iOS app. Alternatively, they may be immediately directed to your app. If your app is mobile only, set should_fallback=false so that if people don't have your app installed, they will be taken to the App Store to download your app. The iOS app link for your content will be sent to your app. To ensure an engaging user experience, you should process the incoming link when your app is activated and direct the person to the object featured in the story they're coming from.

Receiving App Links

Your app will receive a link where {url} is the incoming URL based on a custom scheme that you have defined for your app. You'll also receive an al_applink_data query parameter with JSON encoded content.

{url}?al_applink_data=
  {
    "target_url": "{the-target-url}",
    "extras": {
        "fb_app_id": {your-fb-app-id},
        "fb_access_token": "{your-access-token}]",
        "fb_expires_in": "3600"
    },
    "referer_app_link": {
        "url": "{your-fb-app-back-link}",
        "app_name": "Facebook"
    }
  }

Where fb_access_token and fb_expires_in are only available if the person has authenticated with Facebook in your app.

Handling App Links

Use Bolts to make it easier to handle an inbound App Link (as well as general inbound deep-links) by providing utilities for processing an incoming URL.

For example, you can use the BFURL utility class to parse an incoming URL in your AppDelegate:

- (BOOL)application:(UIApplication *)application
            openURL:(NSURL *)url
  sourceApplication:(NSString *)sourceApplication
         annotation:(id)annotation {
    BFURL *parsedUrl = [BFURL URLWithInboundURL:url sourceApplication:sourceApplication];
    
    // Use the target URL from the App Link to locate content.
    if ([parsedUrl.targetURL.pathComponents[1] isEqualToString:@"profiles"]) {
        // Open a profile viewer.
    }

    // You can also check the query string easily.
    NSString *query = parsedUrl.targetQueryParameters[@"query"];

    // Apps that have existing deep-linking support and map their App Links to existing
    // deep-linking functionality may instead want to perform these operations on the input URL.
    // Use the target URL from the App Link to locate content.
    if ([parsedUrl.inputURL.pathComponents[1] isEqualToString:@"profiles"]) {
        // Open a profile viewer.
    }

    // You can also check the query string easily.
    NSString *query = parsedUrl.inputQueryParameters[@"query"];

    // Apps can easily check the Extras and App Link data from the App Link as well.
    NSString *fbAccessToken = parsedUrl.appLinkExtras[@"fb_access_token"];
    NSDictionary *refererData = parsedUrl.appLinkExtras[@"referer"];
}
    ...
}

Navigate to a URL

Following an App Link allows your app to provide the best user experience (as defined by the receiving app) when a user navigates to a link. Bolts makes this process simple, automating the steps required to follow a link:

1. Resolve the App Link by getting the App Link metadata from the HTML at the URL specified.
2. Step through App Link targets relevant to the device being used, checking whether the app that can handle the target is present on the device.
3. If an app is present, build a URL with the appropriate `al_applink_data` specified and navigate to that URL.
4. Otherwise, open the browser with the original URL specified.

In the simplest case, it takes just one line of code to navigate to a URL that may have an App Link:

[BFAppLinkNavigation navigateToURLInBackground:url];

Adding App and Navigation Data

Under most circumstances, the data that will need to be passed along to an app during a navigation will be contained in the URL itself, so that whether or not the app is actually installed on the device, users are taken to the correct content. Occasionally, however, apps will want to pass along data that is relevant for app-to-app navigation, or will want to augment the App Link protocol with information that might be used by the app to adjust how the app should behave (e.g. showing a link back to the referring app).

If you want to take advantage of these features, you can break apart the navigation process. First, you must have an App Link to which you wish to navigate:

[[BFAppLinkNavigation resolveAppLinkInBackground:url] continueWithSuccessBlock:^id(BFTask *task) {
    BFAppLink *link = task.result;
}];

Then, you can build an App Link request with any additional data you would like and navigate:

BFAppLinkNavigation *navigation = [BFAppLinkNavigation navigationWithAppLink:link
                                                                      extras:@{ @"access_token": @"t0kEn" }
                                                                 appLinkData:@{ @"ref": @"12345" }];
NSError *error = nil;
[navigation navigate:&error];

Resolving App Link Metadata

Bolts allows for custom App Link resolution, which may be used as a performance optimization (e.g. caching the metadata) or as a mechanism to allow developers to use a centralized index for obtaining App Link metadata. A custom App Link resolver just needs to be able to take a URL and return a BFAppLink containing the ordered list of BFAppLinkTargets that are applicable for this device. Bolts provides one of these out of the box that performs this resolution on the device using a hidden WKWebview.

You can use any resolver that implements the BFAppLinkResolving protocol by using one of the overloads on BFAppLinkNavigation:

[BFAppLinkNavigation navigateToURLInBackground:url
                                      resolver:resolver];

Alternatively, a you can swap out the default resolver to be used by the built-in APIs:

[BFAppLinkNavigation setDefaultResolver:resolver];
[BFAppLinkNavigation navigateToURLInBackground:url];

App Link Return-to-Referer View

When an application is opened via an App Link, a banner allowing the user to "Touch to return to " should be displayed. The BFAppLinkReturnToRefererView provides this functionality. It will take an incoming App Link and parse the referer information to display the appropriate calling app name.

- (void)viewDidLoad {
  [super viewDidLoad];

  // Perform other view initialization.

  self.returnToRefererController = [[BFAppLinkReturnToRefererController alloc] init];

  // self.returnToRefererView is a BFAppLinkReturnToRefererView.
  // You may initialize the view either by loading it from a NIB or programmatically.
  self.returnToRefererController.view = self.returnToRefererView;

  // If you have a UINavigationController in the view, then the bar must be shown above it.
  [self.returnToRefererController]
}

The following code assumes that the view controller has an openedAppLinkURL NSURL property that has already been populated with the URL used to open the app. You can then do something like this to show the view:

- (void)viewWillAppear {
  [super viewWillAppear];

  // Show only if you have a back AppLink.
  [self.returnToRefererController showViewForRefererURL:self.openedAppLinkURL];
}

In a navigation-controller view hierarchy, the banner should be displayed above the navigation bar, and BFAppLinkReturnToRefererController provides an initForDisplayAboveNavController method to assist with this.

Analytics

Bolts introduces Measurement Event. App Links posts three different Measurement Event notifications to the application, which can be caught and integrated with existing analytics components in your application.

al_nav_out — Raised when your app switches out to an App Links URL. al_nav_in — Raised when your app opens an incoming App Links URL. al_ref_back_out — Raised when your app returns back the referrer app using the built-in top navigation back bar view.

Listen for App Links Measurement Events

There are other analytics tools that are integrated with Bolts' App Links events, but you can also listen for these events yourself:

[[NSNotificationCenter defaultCenter] addObserverForName:BFMeasurementEventNotificationName object:nil queue:nil usingBlock:^(NSNotification *note) {
    NSDictionary *event = note.userInfo;
    NSDictionary *eventData = event[BFMeasurementEventArgsKey];
    // Integrate to your logging/analytics component.
}];

App Links Event Fields

App Links Measurement Events sends additional information from App Links Intents in flattened string key value pairs. Here are some of the useful fields for the three events.

Installation

You can download the latest framework files from our Releases page.

Bolts is also available through CocoaPods. To install it simply add the following line to your Podfile:

pod 'Bolts'