Adding Facebook Login
Facebook Login for iOS enables your app to obtain an access token to interact with Facebook services on behalf of a person using the app. You can use this feature in place of building your own login and authentication system.
Today there are three ways a person can log in to Facebook using an iOS app. Originally using Facebook Login in your iOS app would show an in-app web view to people using your app. In late 2010 we introduced a faster technique that enabled one-click access using the native Facebook for iOS app. In iOS 6, Apple built Facebook integration into iOS directly, further simplifying the process. More recently, you can show a native login dialog within the Facebook for iOS app.
You may refer to the using Facebook Login document to see a comparison of the various login experiences available to your app.
The Facebook SDK for iOS automatically chooses the best option when someone using your app attempts to use Facebook Login. If a person previously gave your app permissions, the SDK immediately returns an OAuth 2 access token to your app, possibly without even displaying a prompt. For this reason, we recommend you always use the Facebook SDK for iOS to log people in to your app.
This article walks through the following topics:
Login setup
In order to use Facebook Login you first need to add the Facebook SDK to your project. The next few steps describe how to do that. If you've already added the Facebook SDK to your project, skip to Step 4.
Step 1: Get Started
See Getting Started with the iOS SDK to learn the basics. Follow the steps in that guide to complete the following tasks:
Install the prerequisites
Install the Facebook iOS SDK
Create a Facebook app
Step 2: Set up your Xcode project
In Getting Started with the iOS SDK, see the ''Start a new Xcode Project'' to set up your Xcode project for Facebook integration. If you have an existing Xcode project, you can skip over the step that asks you to create a new project. Follow all the other steps in that section.
Step 3: Include the Facebook SDK
In your app delegate header, add code to include the Facebook SDK:
#import <FacebookSDK/FacebookSDK.h>
Step 4: Implement login
The flow involves adding a login button that initiates Facebook Login when it's clicked. The FBSession class has properties you use to open and check the state of the Facebook session object. The FBSession method that handles opening the session can be passed a completion handler that can be used to detect session changes. We will make use of notifications to broadcast session changes that your classes can then use to control their UI.
First, add a button to your view controller and set up the button to initiate the login flow. Let's assume that you wired this button to an action method called authButtonAction:.
Next, open up your app delegate header file and define a global variable that is used for notifications:
extern NSString *const FBSessionStateChangedNotification;
Then open up your app delegate implementation file and define the notification string:
NSString *const FBSessionStateChangedNotification =
@"com.example.Login:FBSessionStateChangedNotification";
Make the notification string unique. For example, change com.example.Login to your app's Bundle Identifier.
Next, open up your app delegate implementation file and add two methods. The first method called openSessionWithAllowLoginUI: is invoked when the login button is clicked or when a check is made for an active session when the main view is initially loaded. This method calls the openActiveSessionWithReadPermissions:allowLoginUI:completionHandler: method of FBSession class to open a Facebook session. The second method called sessionStateChanged:state:error: defines the completion handler. The completion handler for the session open method handles all the session state change functions, including checking the authorization callback and monitoring any subsequent session state changes. Add these two new methods:
/*
* Callback for session changes.
*/
- (void)sessionStateChanged:(FBSession *)session
state:(FBSessionState) state
error:(NSError *)error
{
switch (state) {
case FBSessionStateOpen:
if (!error) {
// We have a valid session
NSLog(@"User session found");
}
break;
case FBSessionStateClosed:
case FBSessionStateClosedLoginFailed:
[FBSession.activeSession closeAndClearTokenInformation];
break;
default:
break;
}
[[NSNotificationCenter defaultCenter]
postNotificationName:FBSessionStateChangedNotification
object:session];
if (error) {
UIAlertView *alertView = [[UIAlertView alloc]
initWithTitle:@"Error"
message:error.localizedDescription
delegate:nil
cancelButtonTitle:@"OK"
otherButtonTitles:nil];
[alertView show];
}
}
/*
* Opens a Facebook session and optionally shows the login UX.
*/
- (BOOL)openSessionWithAllowLoginUI:(BOOL)allowLoginUI {
return [FBSession openActiveSessionWithReadPermissions:@[@"basic_info"]
allowLoginUI:allowLoginUI
completionHandler:^(FBSession *session,
FBSessionState state,
NSError *error) {
[self sessionStateChanged:session
state:state
error:error];
}];
}
Now, add the openSessionWithAllowLoginUI: to the app delegate header file, so your view controller can invoke it:
- (BOOL)openSessionWithAllowLoginUI:(BOOL)allowLoginUI;
If you want to ask for additional permissions, modify the FBSession initialization in the openSessionWithAllowLoginUI: method. For example, to ask for email and user_likes permissions, use the following code:
- (BOOL)openSessionWithAllowLoginUI:(BOOL)allowLoginUI {
NSArray *permissions = @[
@"basic_info",
@"email",
@"user_likes"];
return [FBSession openActiveSessionWithReadPermissions:permissions
allowLoginUI:allowLoginUI
completionHandler:^(FBSession *session,
FBSessionState state,
NSError *error) {
[self sessionStateChanged:session
state:state
error:error];
}];
}
You can only ask for read permissions when opening the session. If you need write permissions, for example, publish_actions, call the requestNewPublishPermissions:defaultAudience:completionHandler: method in the FBSession class. As a best practice you should ask for write permissions in context, so it is clear to the person using your app why you're requesting that access. As an example, ask for publish_actions when someone chooses to publish an action to the timeline. Refer to the permissions guide for more information on permissions.
The login flow differs if the person using your app is running iOS6 or older. For versions older than iOS6, during the login flow your app will pass control to the Facebook iOS app or Facebook in mobile Safari. After authentication, control will pass back your app with the session information in a specially encoded URL. To properly record this information, you need to give the Facebook SDK a chance to process incoming URLs. In iOS6, the login flow gets people's credentials from iOS and they are not transitioned to the Facebook app. The Facebook SDK takes care of these interactions and all you have to do is call the required FBSession methods.
In the app delegate, implement the application:openURL:sourceApplication:annotation: delegate method to call the Facebook session object:
/*
* If we have a valid session at the time of openURL call, we handle
* Facebook transitions by passing the url argument to handleOpenURL
*/
- (BOOL)application:(UIApplication *)application
openURL:(NSURL *)url
sourceApplication:(NSString *)sourceApplication
annotation:(id)annotation {
// attempt to extract a token from the url
return [FBSession.activeSession handleOpenURL:url];
}
The flow back to your app may be interrupted, for example, if a person clicks the Home button if authenticating via the Facebook for iOS app. If this happens, the Facebook SDK can take care of any cleanup, which may include starting a fresh session. To enable this, in the applicationDidBecomeActive: delegate method call the active session's handleDidBecomeActive method:
// We need to properly handle activation of the app with regards to Facebook Login
// (e.g., returning from iOS 6.0 Login Dialog or from fast app switching).
[FBSession.activeSession handleDidBecomeActive];
You should also take care of closing the session if the app is about to terminate. Do this by adding the following code to the applicationWillTerminate: app delegate method for the person using the app:
[FBSession.activeSession close];
Now that you have set up the authentication code in the app delegate, go back to your view controller implementation file to invoke the authentication methods. First, include the app delegate header file:
#import "AppDelegate.h"
Next, in the authButtonAction method fill out the implementation to invoke the openSessionWithAllowLoginUI: method you defined in the app delegate:
- (IBAction)authButtonAction:(id)sender {
AppDelegate *appDelegate = [[UIApplication sharedApplication] delegate];
// The person using the app has initiated a login, so call the openSession method
// and show the login UX if necessary.
[appDelegate openSessionWithAllowLoginUI:YES];
}
Build and run the project. When the login button is clicked, you should see something like this:
You should also see an NSLog showing that a valid user session has been found:
2012-08-10 18:02:24.529 TestLogin[47133:c07] User session found
Once you've verified the login flow, you can remove the NSLog statement in the sessionStateChanged:state:error: method defined in your app delegate implementation file.
You'll notice that even though you've logged in, the login button is still labeled ''Login''. You'll take care of this in the next step.
Step 5: Implement logout
For simplicity, we assume you'll use the same button for logging a person in and out. Add an outlet named ''authButton'' to the login button you set up previously. Use this to control the button text when the person is logged in versus logged out.
Now, set up a new method in the app delegate implementation file that handles logging out:
- (void) closeSession {
[FBSession.activeSession closeAndClearTokenInformation];
}
Next, add this new method to the app delegate header file:
- (void) closeSession;
Now, make the following changes to your view controller. Modify the authButtonAction: method to detect the session validity and log the person in or out:
- (IBAction)authButtonAction:(id)sender {
AppDelegate *appDelegate =
[[UIApplication sharedApplication] delegate];
// If the person is authenticated, log out when the button is clicked.
// If the person is not authenticated, log in when the button is clicked.
if (FBSession.activeSession.isOpen) {
[appDelegate closeSession];
} else {
// The person has initiated a login, so call the openSession method
// and show the login UX if necessary.
[appDelegate openSessionWithAllowLoginUI:YES];
}
}
Then, in the viewDidLoad method, register for the session change notification you defined in the app delegate by adding this code to the end of the method:
[[NSNotificationCenter defaultCenter]
addObserver:self
selector:@selector(sessionStateChanged:)
name:FBSessionStateChangedNotification
object:nil];
Unregister for the notifications by adding the following code to the end of the didReceiveMemoryWarning method:
[[NSNotificationCenter defaultCenter] removeObserver:self];
Next, define a new private method sessionStateChanged: to change the button text:
- (void)sessionStateChanged:(NSNotification*)notification {
if (FBSession.activeSession.isOpen) {
[self.authButton setTitle:@"Logout" forState:UIControlStateNormal];
} else {
[self.authButton setTitle:@"Login" forState:UIControlStateNormal];
}
}
Finally, modify the viewDidLoad method to show the logged in versus logged out button by calling the app delegate openSessionWithAllowLoginUI: method to check for a cached token. While checking the cached token, you are setting a flag to open a session while avoiding a login UI flow. Add this code to the end of the method:
// Check the session for a cached token to show the proper authenticated
// UI. However, since this is not intitiated by the person using your app, do not show the login UX.
AppDelegate *appDelegate = [[UIApplication sharedApplication] delegate];
[appDelegate openSessionWithAllowLoginUI:NO];</pre>
Build and run the project. Since the session should be active from your first run, the button should be set to ''Logout''.
Click on the button to log out the person. The button text should change to ''Login''. Clicking the button again should switch you to the Facebook app (iOS or mobile Safari) and show you an interstitial screen with an ''OK'' button. We'll talk about how to get rid of this interstitial screen in the next section.
Best practices
Pro tip 1: Include Facebook Login when people register
Apps often only use Facebook Login when asking a person to enable Facebook features in the app. You should also include Facebook Login anywhere you prompt a person to register for your app, which usually shows up the first time a person launches an app. People can enjoy a simplified registration process, and you can request the same information that you would normally collect manually (ex: email address).
Pro tip 2: Request only the permissions your app needs
Because so much personal information is stored by people using Facebook, we have a very extensive permission system to protect their privacy. In particular, certain permissions (called extended permissions) are shown separately during login, and people are given an opportunity to opt-out of them individually.
In general, you will get the best login rate if you only request the permissions you need to register them and use your basic features. If you need additional permissions later, you can always request them at a time when someone is better informed about your app and why you might need them.
More information about our privacy system can be found in this blog post.
Pro tip 3: Do not request offline_access or publish_stream
In the past, using Facebook services when someone was not actively interacting with your app required a special permission called 'offline_access'. This permission is no longer required and will soon be deactivated. If you have an older app that uses this permission, you should read about upgrading access tokens.
Also, many apps incorrectly ask for publish_stream to add content to a person's News Feed. This permission tends to hurt conversion and is almost never needed. Instead, consider publishing Open Graph actions with publish_actions or using our Feed Dialog - which does not require this permission.
Pro tip 4: Complete all iOS app settings
Fill out every field related to your app in the Native iOS App section of Basic Settings in the App Dashboard. If these fields are not configured, we can't drive traffic to your app or the iOS App Store.
In addition, we use the iOS Bundle ID to streamline authentication for people who already authenticated your app.
Updated last Thursday