Facebook iOS SDK: Let users Connect & Login with FB

Here's how to let your users connect and login to your iOS app using Facebook. The first thing you got to do is download the Facebook iOS SDK. If you have Git installed, you can also do this by pulling from GitHub.

git clone git://github.com/facebook/facebook-ios-sdk.git

Making the Sample Application Work

The SDK comes with a sample application that demonstrates authorization, making API calls, and invoking a dialog, to guide you in development.

To build and run the sample application with Xcode (4):

• Open the included Xcode Project File by selecting File->Open... and selecting sample/DemoApp/DemoApp.xcodeproj.
• Verify your compiler settings by checking the menu items under Project->Set Active SDK and Project->Set Active Executable. For most developers, the defaults should be OK. Note that if you compile against a version of the iOS SDK that does not support multitasking, not all features of the Facebook SDK may be available. See the "Debugging" section below for more information.
• Create a Facebook App ID (see http://www.facebook.com/developers/createapp.php)
• Specify your Facebook AppId in DemoAppViewController.m and DemoApp-Info.plist (under URL types > Item 0 > URL Schemes > Item 0) 
• Finally, select Build->Build and Run. This should compile the application and launch it.

Setting the AppId in DemoAppViewController.m

Setting the AppId in DemoApp-Info.plist

Note: If you failed to set this properly, you won't be able to receive anything on your callback. In other words, the method `fbDidLogin` of FBSessionDelegate will never be called.


Integrate With Your Own Application

If you want to integrate Facebook with an existing application, then follow these steps:

• Copy the Facebook SDK into your Xcode project:
• In Xcode, open the Facebook SDK by selecting File->Open... and selecting src/facebook-ios-sdk.xcodeproj.
• With your own application project open in Xcode, drag and drop the "FBConnect" folder from the Facebook SDK project into your application's project.
• Include the FBConnect headers in your code: #import "FBConnect/FBConnect.h"
• You should now be able to compile your project successfully.

• Register your application with Facebook:
• Create a new Facebook application at: http://www.facebook.com/developers/createapp.php. If you already have a related web application, you can use the same application ID.
• Set your application's name and picture. This is what users will see when they authorize your application.

Usage

Begin by instantiating the Facebook object:

    Facebook* facebook = [[Facebook alloc] initWithAppId:appId andDelegate:self];

Where appId is your Facebook application ID string and delegate is the delegate object you wish to receive callbacks.

With the iOS SDK, you can do three main things:

• Authentication and Authorization: Prompt users to log in to Facebook and grant permissions to your application.
• Make API Calls: Fetch user profile data, as well as information about a user's friends.
• Display a Dialog: Interact with a user via a UIWebView--this is useful for enabling quick Facebook interactions (such as publishing to a user's stream) without requiring upfront permissions or implementing a native UI.

Authentication and Authorization

Authorizing a user allows your application to make authenticated API calls on the user's behalf. By default your application will have access to the user's basic information, including their name, profile picture, and their list of friends, along with any other information the user has made public. If your application requires access to private information, it may request (http://developers.facebook.com/docs/authentication/permissions)[additional permissions].

To authorize a user, do the following:

• Bind your application to a URL scheme corresponding to your Facebook application ID. The URL scheme you must bind to is of the format "fb[appId]://", where [appId] is your Facebook application ID. Without this, your application won't be able to handle authorization callbacks. Modify your application's .plist file as follows:
• Under the root key ("Information Property List") add a new row and name the key "URL types".
• Under the "URL types" key that you just added, you should see a key named "Item 0". If not, add a new row with key "Item 0".
• Under the "Item 0" key, add a new row and name the key "URL Schemes".
• Under the "URL Schemes" key that you just added, you should see a key named "Item 0". If not, add a new row with key "Item 0".
• Set the value of "Item 0" to "fb[appId]" where [appId] is your Facebook application ID. Make sure there are no spaces anywhere in this value. For example, if your application's id is 1234, the value should be "fb1234".

• Modify your application's main AppDelegate class as follows:
• Add a method with the following signature (if it doesn't exist alrady):
• (BOOL)application:(UIApplication *)application handleOpenURL:(NSURL *)url
• In this method, call your application's Facebook object's handleOpenURL method, making sure to pass in the url parameter.

• Finally, make a call to the authorize method:
  
  Facebook* facebook = [[Facebook alloc] initWithAppId:appId andDelegate:self];
  [facebook authorize:permissions];

Where appId is your Facebook application ID string, permissions is an array of strings containing each permission your application requires, and delegate is the delegate object you wish to receive callbacks. For more information, refer to the code or sample application.

See the sample application for a more specific code example.



Single Sign-On

In the initial release of the SDK, the authorize method always opened an inline dialog containing a UIWebView in which the authorization UI was shown to the user. Each iOS application has its own cookie jar, so this mechnism had a major disadvantage: it required users to enter their credentials separately for each app they authorized.

In the updated version of the SDK, we changed the authorization mechanism so that users no longer have to re-enter their credentials for every application on the device they want to authorize. The new mechanism relies on iOS's fast app switching. It works as follows:

If the app is running in a version of iOS that supports multitasking, and if the device has the Facebook app of version 3.2.3 or greater installed, the SDK attempts to open the authorization dialog withing the Facebook app. After the user grants or declines the authorization, the Facebook app redirects back to the calling app, passing the authorization token, expiration, and any other parameters the Facebook OAuth server may return.

If the device is running in a version of iOS that supports multitasking, but it doesn't have the Facebook app of version 3.2.3 or greater installed, the SDK will open the authorization dialog in Safari. After the user grants or revokes the authorization, Safari redirects back to the calling app. Similar to the Facebook app based authorization, this allows multiple applications to share the same Facebook user session through the Safari cookie.

If the app is running a version of iOS that does not support multitasking, the SDK uses the old mechanism of popping up an inline UIWebView, prompting the user to log in and grant access. The FBSessionDelegate is a callback interface that your application should implement: it's methods will be invoked when the application successful login or logout.





Logging Out

When the user wants to stop using Facebook integration with your application, you can call the logout method to clear all application state and make a server request to invalidate the current access token.

    [facebook logout:self];

Note that logging out will not revoke your application's permissions, but simply clears your application's access token. If a user that has previously logged out of your application returns, he will simply see a notification that he's logging into your application, not a notification to grant permissions. To modify or revoke an application's permissions, a user must visit the "Applications, Games, and Websites" tab of their Facebook privacy settings dashboard.




Making API Calls

The Facebook Graph API presents a simple, consistent view of the Facebook social graph, uniformly representing objects in the graph (e.g., people, photos, events, and fan pages) and the connections between them (e.g., friend relationships, shared content, and photo tags).

You can access the Graph API by passing the Graph Path to the request() method. For example, to access information about the logged in user, call

    [facebook requestWithGraphPath:@"me" andDelegate:self];             // get information about the currently logged in user
    [facebook requestWithGraphPath:@"platform/posts" andDelegate:self]; // get the posts made by the "platform" page
    [facebook requestWithGraphPath:@"me/friends" andDelegate:self];     // get the logged-in user's friends

Your delegate object should implement the FBRequestDelegate interface to handle your request responses.

Note that the server response will be in JSON string format. The SDK uses an open source JSON library (http://code.google.com/p/json-framework/) to parse the result. If a parsing error occurs, the SDK will callback request:didFailWithError: in your delegate.

A successful request will callback request:didLoad: in your delegate. The result passed to your delegate can be an NSArray, if there are multiple results, or an NSDictionary if there is only a single result.

Advanced applications may want to provide their own custom parsing and/or error handling, depending on their individual needs.

The Old REST API is also supported. To access REST methods, pass in the named parameters and the method name as an NSDictionary.

    NSMutableDictionary* params = [NSMutableDictionary dictionaryWithObjectsAndKeys: @"4", @"uids", @"name", @"fields", nil];
    [facebook requestWithMethodName: @"users.getInfo" andParams: params andHttpMethod: @"GET" andDelegate: self];

Related posts:

• Facebook iOS: Use Access Token in PHP
• Grab the Picture of a Facebook Graph Object
• Facebook fb:multi-friend-selector In Tab Page