iOS 6 Integration

Overview

Apple added features in iOS 6 that help native mobile developers build great users experiences on iOS devices. The new APIs include:

• Using the native Login Dialog and tips
• Posting to Facebook with the native controller

Learn how to get started using these features below.

Using the native Login Dialog

The Login Dialog built into iOS 6 gives developers a native way to use Facebook Login in their apps without having to make a fast-app-switch. Note, to use iOS 6 native auth, apps need change the way they request permissions from users - apps must separate their requests for read and write permissions. The Facebook SDK for iOS supports these features and helps developers use them to build apps that work on multiple iOS versions and device configurations.

The example app described here is a social photo sharing app that needs basic permission, permission to read photos from a user and their friends, and permission to post photos on the user's behalf. Using the native Login Dialog, it will make three permission requests when the user takes three distinct actions:

• Request basic permissions. Made when the user first connects the app to their Facebook account.
• Request other read permissions: user_photos, friends_photos. Made when the user opens the app's shared photo stream.
• Request publish permission: publish_actions. Made when the app first tries to post a photo on the user's behalf.

The native Login Dialog uses the same permission names that developers are experienced with. The permissions are described here.

Step 1: Request basic profile information

Apps must have a basic connect to a user's Facebook account to ask for permission to post on the user's behalf or to read other fields from the user's timeline or their friends' timelines - for example, the user's photos, friends' photos, the user's likes, etc.

To create this basic connection using the iOS 6 native Login Dialog, apps should request access to a user's basic profile information by asking for one of email, user_birthday, or user_location permissions. If no permissions are requested, the Facebook SDK will automatically request email permissions. Make this request using the Facebook SDK for iOS using:

// If a user has *never* logged into your app, request one of
// "email", "user_location", or "user_birthday". If you do not
// pass in any permissions, "email" permissions will be automatically
// requested for you. Other read permissions can also be included here.
NSArray *permissions = 
    [NSArray arrayWithObjects:@"email", nil];

[FBSession openActiveSessionWithReadPermissions:permissions
                                   allowLoginUI:YES
                              completionHandler:^(FBSession *session, FBSessionState status, NSError *error) {
                                  /* handle success + failure in block */
                              }];

When a user clicks “OK”, the app is granted access to the user's basic profile info along with email, user_location, and user_birthday permissions.

Permissions that indicate a request for basic profile info:

Permissions
email	user_birthday	user_location

Step 2: Request read permissions

A feature of the example social photo sharing app is a shared photo stream. To fill the stream with photos, the user must grant the app two "read permissions" that let the app read the user's photos and their friends' photos. To make this request with the Facebook SDK, use:

NSArray *permissions = 
    [NSArray arrayWithObjects:@"user_photos", @"friends_photos", nil];

[[FBSession activeSession] reauthorizeWithReadPermissions:permissions
                                        completionHandler:^(FBSession *session, NSError *error) {
                                            /* handle success + failure in block */
                                        }];

Read permissions include:

Permissions
user_about_me	friends_about_me	user_activities
friends_activities	user_birthday	friends_birthday
user_checkins	friends_checkins	user_education_history
friends_education_history	user_events	friends_events
user_groups	friends_groups	user_hometown
friends_hometown	user_interests	friends_interests
user_likes	friends_likes	user_notes
friends_notes	user_online_presence	friends_online_presence
user_interests	friends_interests	user_likes
friends_likes	user_notes	friends_notes
user_online_presence	friends_online_presence	user_religion_politics
friends_religion_politics	user_status	friends_status
user_subscriptions	friends_subscriptions	user_videos
friends_videos	user_website	friends_website
user_work_history	friends_work_history	read_friendlists
read_mailbox	read_requests	read_stream
read_insights	xmpp_login

Step 3: Request publish permissions

Another feature of the example photo sharing app is to let users share photos on Facebook. The user must grant the app a "publish permission" to share photos. The first time a user clicks "Share" to post a photo, the app will request the publish_actions permission. To make this request with the Facebook SDK, use:

// can include any of the "publish" or "manage" permissions
NSArray *permissions = 
    [NSArray arrayWithObjects:@"publish_actions”, nil];

[[FBSession activeSession] reauthorizeWithPublishPermissions:permissions
                                             defaultAudience:FBSessionDefaultAudienceFriends
                                           completionHandler:^(FBSession *session, NSError *error) {
                                               /* handle success + failure in block */
                                           }];

The reauthorizeWithPublishPermissions method can also be used to request "manage" permissions.

Publish permissions include:

Permissions
ads_management	create_event	rsvp_event
manage_friendlists	manage_notifications	manage_pages
publish_actions

Tips for using the native Login Dialog

Tip 1: Use the Facebook SDK for iOS to implement Facebook login

If the user hasn't signed into Facebook on their iOS 6 device or if the device runs an older version of iOS, apps cannot use the native Login Dialog. To ensure that apps work in these situations, developers should use the Facebook SDK for iOS, which will fallback to the fast-app-switch to the native Facebook app (if available) or Safari.

Tip 2: Connecting to an existing user's Facebook account

In some cases, the iOS device won't have an access token for a user who has already connected an app to their Facebook account. This can happen when a user used an app's website or used the app on another mobile device. To use the iOS 6 native Login Dialog, apps need to "import" the user's credentials into the device and need to show the iOS 6 native Login Dialog. A good way to do this is to request basic profile information - see Step 1 above.

Note: if an app already has an access token for a user, it usually should not import that token into the iOS 6 account store. Doing that requires app users who already use an app on their device to click through an unnecessary Login Dialog.

Tip 3: Support for the offline_access permission

The iOS 6 Login Dialog does not support the deprecated offline access permission, and apps using the new integration will not be able to use it.

Tip 4: Get the user’s access token from iOS 6

Once a user has granted your app access to their Facebook account on an iOS device, you can read the user’s access token from your active FBSession:

[[FBSession activeSession] accessToken];

This can be useful for debugging purposes or if your app’s servers need to make Facebook API calls on behalf of the user. Note, this token is still bound to the iOS device and if the user disallows your app from accessing their Facebook account on that iOS device, the token will expire.

Tip 5: Disabling the native Login Dialog

In some cases, apps may choose to disable the native Login Dialog to use new versions of the Facebook SDK but to avoid rewriting the ways they request permissions from users. To use the previous behavior of fast-app-switch for login, use the deprecated FBSession methods openActiveSessionWithPermissions and reauthorizeWithPermissions.

Tip 6: Request read permissions along with basic profile info

In some cases, it will make sense for the app to request both basic profile info and the photo permissions at the same time. This can be done using:

NSArray *permissions = 
    [NSArray arrayWithObjects:@"email", @”user_photos”, @”friends_photos”, nil];

[FBSession openActiveSessionWithReadPermissions:permissions
                                   allowLoginUI:YES
                              completionHandler:^(FBSession *session, FBSessionState status, NSError *error) {
                                  /* handle success + failure in block */
                              }];
}];

Posting to Facebook with the iOS 6 Share Sheet

iOS 6 includes a native Share Sheet that lets users post status updates, photos, links, and locations to Facebook and includes support for setting the audience for the post and tagging the post with a location. The Facebook SDK supports the use of this native controller.

Use of the iOS 6 Share Sheet is subject to Facebook's Platform Policies, especially section 4.2 which states that apps may not pre-fill. In the context of the Share Sheet, this means apps may not pre-fill the Share Sheet's initialText field with content that wasn't manually generated by users earlier in the app's workflow.

While you can use the iOS6 native view controller API directly there are a few reasons to use the one provided by the Facebook SDK. Using the native Share dialog provided by the Facebook SDK for iOS provides a quick way to test that the user has signed into Facebook on their iOS6 device. This API also uses the same style block as other parts of the Facebook SDK. To show the native iOS6 share dialog, use:

BOOL displayedNativeDialog =
    [FBNativeDialogs
     presentShareDialogModallyFrom:self
     initialText:@"" 
     image:[UIImage imageNamed:@"testimage.png"]
     url:[NSURL URLWithString:@"http://www.example.com"]
     handler:^(FBNativeDialogResult result, NSError *error) {
         if (error) {
             /* handle failure */
         } else {
             if (result == FBNativeDialogResultSucceeded) {
                 /* handle success */
             } else {
                 /* handle user cancel */
             }
         }
    }];
if (!displayedNativeDialog) {
    /* 
      Fallback to web-based Feed Dialog:
      https://developers.facebook.com/docs/howtos/feed-dialog-using-ios-sdk/
     */
}