Link To Your Native App

Social App Discovery on Mobile was introduced in October 2011, so you can drive distribution directly to native iOS apps. In February 2012, we introduced granular controls that let you give users an optimal experience when sending traffic to your apps from Facebook for iPhone.

If your app has Login with Facebook, people can find it through Facebook for iPhone. This diagram shows how distribution flows from when a user first interacts with an app, publishes a news story or sends an app request, to how the stories and request notifications go back to your app. The diagram also shows how search and bookmarks can help more people find your app from Facebook for iPhone.

When a user taps on an app notification or clicks a story that links to your app, they'll get the original URL. This can be used to deeply link into your app. The notification URL or news feed URL is sent to the app in the target_url parameter of the callback link. You can modify the application:handleOpenURL: or application:openURL:sourceApplication:annotation: methods in the app delegate implementation file to customize how your app handles these notifications.

If the user installed your app and authenticated with Facebook, this URL opens:

fb[app id]://authorize#expires_in=0&access_token=[token]&target_url=[Linked URL]

If the app is installed, but the user has not authenticated with Facebook, the URL format is:

fb[app id]://authorize#target_url=[Linked URL]

To summarize, these are the channels that drive people back to your app:

• App Search: your app is visible if it passes an active usage threshold.
• App Bookmarks: your app is visible to people who previously used it, based on a usage threshold.
• App Request Notifications: requests 2.0 notifications from friends link to your app.
• Story Attribution: your app source attribution is visible if you set up your app with a namespace.
• Story Links: you can configure links in your news feed and timeline stories that point back to your app.

This article outlines how to configure distribution to your native iOS apps. We'll also walk through tips to help you optimize the user experience for story links.

Understanding App Dashboard Settings

You can set up and configure distribution from the Facebook iOS app to your app in the App Dashboard. To enable requests, bookmarks and search results to link to your app, configure your settings as follows:

• Bundle ID: Enter an iOS Bundle ID that corresponds to your app.
• iPhone App Store ID: Enter an iPhone App Store ID if your app is listed in the iPhone App Store. You may enter ''0'' if your app is not listed or if you do not support an iPhone version. If you wish to test the App Store link flow, you can also temporarily enter a valid App Store ID for an existing app in the App Store.
• iPad App Store ID: Enter an iPad App Store ID if your app is listed in the iPad App Store. This entry may be the same as your iPhone App Store setting if you have a universal app. It may be a different ID if you have separate iPhone and iPad versions of your app. If your app is not supported for iPad, you should enter ''0''.
• Facebook Login: Enable this setting.

By default, published news feed or open graph stories link back to the provided story URL. For example, you may link these stories to your mobile site or an intermediate page that redirects to a mobile site, desktop page or native URL.

To let these stories deeply link back to your iOS app or the App Store if the app is not installed, you must configure this additional setting:

• Deep Linking: Enable this setting.

You may want to turn on this setting after you've optimized your iOS native app user experience for deep linking. Keep in mind that when you publish a link, a user can click on it from Facebook in a number of contexts, including a desktop browser, Android browser, iOS mobile browser, native Android app or native iOS app. This setting helps you enrich the linking behavior to your iOS app, but the link you provide should work well in all other contexts.

Now we'll show you how to implement deep linking to optimize your user experience and encourage people to come back to your app.

How to handle deep links to provide a more relevant user experience

When someone taps a deep link in the Facebook for iPhone app, the user is immediately directed to your iOS app. If the app is not installed, the user is taken to the App Store to download your app. To ensure an engaging user experience, you should process the incoming link when your app is activated. For example, a news app will have the incoming link correspond to a news story. Direct the user straight to that story, instead of a generic app landing page.

Your app is invoked in one of two ways:

1) If the user authenticated your app:

fb[APP_ID]://authorize#expires_in=[ACCESS_TOKEN_EXPIRATION]&access_token=[USER_ACCESS_TOKEN]&target_url=[ORIGINAL_LINK]

2) If the user hasn't authenticated your app:

fb[APP_ID]://authorize#target_url=[ORIGINAL_LINK]

Where [ORIGINAL_LINK] corresponds to the link in your app, for example, http://pinterest.com/aryehs/cool/.

You can parse the target_url to deep link your users to the right content in your app.

Your user experience may not depend on the user being logged in. If this is the case, handle the logged in and logged out flows in the same way. You can do this in the App delegate methods that are invoked when someone opens your app, such as the application:openURL:sourceApplication:annotation: method.

If your app requires an authorized user, handle the processing of the target URL in the SDK callbacks implemented after a successful login.

We will show code for the case where the user doesn't need to be logged in. We'll add this code to the application:openURL:sourceApplication:annotation: app delegate method, where we'll check for a target URL.

In the code sample, we're simply displaying an alert view to the user, but you could direct users through the appropriate flow for your app.

/**
 * A function for parsing URL parameters.
 */
- (NSDictionary*)parseURLParams:(NSString *)query {
    NSArray *pairs = [query componentsSeparatedByString:@"&"];
    NSMutableDictionary *params = [[NSMutableDictionary alloc] init];
    for (NSString *pair in pairs) {
        NSArray *kv = [pair componentsSeparatedByString:@"="];
        NSString *val = [[kv objectAtIndex:1]
            stringByReplacingPercentEscapesUsingEncoding:NSUTF8StringEncoding];
        [params setObject:val forKey:[kv objectAtIndex:0]];
    }
    return params;
}

- (BOOL)application:(UIApplication *)application 
        openURL:(NSURL *)url 
        sourceApplication:(NSString *)sourceApplication 
        annotation:(id)annotation {
    // To check for a deep link, first parse the incoming URL
    // to look for a target_url parameter
    NSString *query = [url fragment];
    if (!query) {
        query = [url query];
    }
    NSDictionary *params = [self parseURLParams:query];
    // Check if target URL exists
    NSString *targetURLString = [params valueForKey:@"target_url"];
    if (targetURLString) {
        NSURL *targetURL = [NSURL URLWithString:targetURLString];
        NSDictionary *targetParams = [self 
                                      parseURLParams:[targetURL query]];
        NSString *deeplink = [targetParams valueForKey:@"deeplink"];
        // Check for the 'deeplink' parameter to check if this is one of
        // our incoming news feed link
        if (deeplink) {
            UIAlertView *alert = [[UIAlertView alloc] 
                initWithTitle:@"News" 
                message:[NSString stringWithFormat:@"Incoming: %@", deeplink]
                delegate:nil 
                cancelButtonTitle:@"OK" 
                otherButtonTitles:nil, 
                nil];
            [alert show];
            [alert release];
        }
    }
    return [FBSession.activeSession handleOpenURL:url];
}

In our sample code set up, we'll inject a deeplink parameter to the news feed story and check it back to signify an incoming story link.

// Method that sets up the news feed story
- (void)apiDialogFeedUser {
    // Dialog parameters - the 'deeplink' we insert will be passed back for use in deep link
    // detection. The 'ref' parameter will be used for analytics.
    NSMutableDictionary *params = [NSMutableDictionary dictionaryWithObjectsAndKeys:
        @"I'm using the Test iOS app", @"name",
        @"Test for iOS.", @"caption",
        @"Check out Test iOS to learn how you can make your iOS apps social using Facebook Platform.", @"description",
        @"http://m.facebook.com/apps/uniquenamespace/?deeplink=news", @"link",
        @"http://www.facebookmobileweb.com/hackbook/img/facebook_icon_large.png", @"picture",
        @"foo", @"ref",
        nil];

    [facebook dialog:@"feed"
        andParams:params
        andDelegate:self];
}

In this simple example, we use the deeplink parameter in the news feed story link to direct users in your app. You could have additional parameters or URL paths to better direct users. Note that whatever URL you specify in your feed story or open graph object will echo back in the target_url passed to your app.

Note: The ref in the feed dialog is a text reference for the post's category. We use this category in Facebook Insights to help you measure how different post types perform. The ref parameter does not appear on the actual posted story, as it is for your reference only.