Apple added features in iOS 6 that help native mobile developers build great users experiences on iOS devices. The new APIs include:
Learn how to get started using these features below.
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.
Note: The native Login Dialog is available after a user has logged into Facebook on their device. If the device isn't connected to Facebook, the native Login Dialog isn't available and permission requests will be made via the fast-app-switch to the Facebook app (if installed) or Safari. The Facebook SDK methods below will seamlessly fallback to this fast-app-switch behavior. To build Facebook-enabled apps that run on all supported iOS versions and devices, we strongly encourage developers to use the Facebook SDK when building iOS apps.
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:
user_photos
, friends_photos
. Made when the user opens the app's shared photo stream.publish_actions
. Made when the app first tries to post a photo on the user's behalf.Best Practice: apps should request permissions in context to improve the user experience and the conversion rate for the request. For example, the sample app only requests `publish_actions` the first time the user posts a checkin.
The native Login Dialog uses the same permission names that developers are experienced with. The permissions are described here.
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 |
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 |
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 |
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.
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.
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.
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.
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
.
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 */ }]; }];
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/ */ }