Improving App Distribution on iOS

When we introduced Social App Discovery on Mobile in October 2011, we enabled distribution directly to native iOS apps. Today, we are introducing granular controls for native iOS apps to provide an optimal user experience when driving traffic to your app from Facebook for iOS.

Understanding the Dev App Settings

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

• Enter an iOS Bundle ID that corresponds to your app
• Enter an iPhone and/or iPad App Store ID
• Enable the "Configured for iOS SSO" setting

By default, published News Feed or Open Graph stories will link back to the provided story URL. For example, you may link these stories to your mobile web site or you may link to an intermediate page that then redirects to either a mobile web site, desktop page, or native URL.

To enable any News Feed and Open Graph stories to deep link back to your iOS app or to the App Store (if the app is not installed) you must configure this additional setting:

• Enable the "iOS native deep linking" setting

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

We will now show you how you can implement deep linking to optimize the experience for your users, drive re-engagements, and close the viral loop.

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

When a link is tapped in the Facebook for iOS app with deep linking enabled, 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. You would want to direct the user straight to that story instead of a generic app landing page.

Your app will be invoked in one of two ways:

1) If the user has authenticated your Facebook App:

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

2) Non-authenticated user:

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 correct content in your app.

Your app user experience may not depend on the user being logged in. If this is the case, you will handle both the logged in and not-logged in flows in the same way. You would do this in the App delegate methods that are invoked when your app is opened, for example the application:openURL:sourceApplication:annotation: method.

If your app requires an authorized user you should handle the processing of the target URL in the SDK call backs implemented after a successful login, the fbDidLogin method.

We will show code for the case where the user does not need to be logged in to properly deep link them. This code is added to the application:openURL:sourceApplication:annotation: app delegate method where we will check for a target URL.

In the code sample we are 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]
        autorelease];
    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];
    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 [facebook handleOpenURL:url];
}

In our sample code set up we will inject a deeplink parameter to the News Feed story and check this same parameter back to signify an incoming News Feed story link.

// Method that sets up the news feed story
- (void)apiDialogFeedUser {
    SBJSON *jsonWriter = [[SBJSON new] autorelease];

    // The action links to be shown with the post in the feed
    NSArray* actionLinks = [NSArray arrayWithObjects:
        [NSDictionary dictionaryWithObjectsAndKeys:
            @"Get Started",@"name",
            @"http://m.facebook.com/apps/uniquenamespace/",@"link",
            nil],
        nil];

    NSString *actionLinksStr = [jsonWriter stringWithObject:actionLinks];

    // 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",
        actionLinksStr, @"actions",
        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 be echoed back in the target_url passed to your app.

Note: The ref in the Feed Dialog is a text reference for the category of the post. This category is used in Facebook Insights to help you measure the performance of different types of post as documented here. The ref parameter does not appear on the actual posted story, it is for your reference only.

View additional step-by-step documentation and sample code in the iOS Getting Started Guide.