Facebook Connect for iPhone

From Facebook Developer Wiki

Jump to: navigation, search

Facebook Connect for iPhone is Objective-C code that lets you connect your users' Facebook accounts with your application. The code provides:

  • A login mechanism.
  • User session data.
  • Integration with Feed.
  • The ability to call methods from the Facebook Platform API and prompt for extended permissions.

You need to use these Facebook Connect for iPhone buttons for Connecting users and logging them out.

You should familiarize yourself with the Platform Principles and Policies.

Contents

Adding Connect to your Xcode Project

To get started, you need to add Facebook Connect for iPhone to your application's Xcode project.

  1. Download Facebook Connect for iPhone code, then unzip the archive.
  2. Open the src/FBConnect.xcodeproj project file.
  3. Drag the FBConnect group into your application's Xcode project. The instructions in this article assume you are not copying the files into your project's group folder.
  4. Make sure that the FBConnect headers are in the include path. Go into your project's settings and enter the relative or absolute path to the src directory (either the directory where you unzipped the SDK files or where you copied them).
  5. Include the FBConnect headers in your code:
#import "FBConnect/FBConnect.h"

You should now be able to compile your project successfully.

Working with Sessions

The central object of FBConnect is the FBSession object. This object represents the session of a user who has authorized and logged in to your Facebook application. To create a session, you need to use your Facebook application's API key and application secret (you find them in the Facebook Developer application at http://www.facebook.com/developers/apps.php):

session = [FBSession sessionForApplication:myApiKey secret:myAppSecret delegate:self];


If you do not want to store your application secret in your code, you can use the getSessionProxy method, which allows you to specify a Session Proxy URL instead of the application secret. This URL gets called to create a session:

session = [FBSession sessionForApplication:myApiKey getSessionProxy:myURL delegate:self];


This URL gets called with an HTTP GET request that includes an auth_token argument. You may use that token to call facebook.auth.getSession yourself on your own servers. The response that your getSessionProxy should return is the same XML response that facebook.auth.getSession returns to you. See Session Proxy for an example written in PHP.

Note: You should store the session object returned by FBSession. Otherwise, future calls to dialog methods will fail.

Session Delegates

In order to declare an object a delegate it must implement the FBSessionDelegate protocol and at least provide the required method:

- (void)session:(FBSession*)session didLogin:(FBUID)uid

The FBSession object is persistent and is shared by other session delegates such as an FBLoginButton and other session delegates you may create yourself. Session delegates are stored in an array that is a property of the FBSession instance. If any of your custom session delegate objects cease to exist without telling your FBSession instance you will likely get a EXC_BAD_ACCESS error and your app will crash. Therefore in your objects that implement the FBSessionDelegate you should remove your object from FBSession's delegate array (assuming you've saved the FBSession as the ivar _session):

- (void) dealloc { [_session.delegates removeObject: self]; }

Logging In

Once you have a session for your application you can ask the user to log in. The easiest way to do this is to add a standard login button to your app:

FBLoginButton* button = [[[FBLoginButton alloc] init] autorelease]; [self.view addSubview:button];


This button will automatically display the login dialog when the user touches it. You can create the login dialog yourself if you don't want to use a standard button:

FBLoginDialog* dialog = [[[FBLoginDialog alloc] initWithSession:session] autorelease]; [dialog show];


FBLoginDialog behaves similarly to Apple's UIAlertView. It takes your user to facebook.com, where the user can enter their email and password. You can set a delegate on the dialog if you want to be notified once the dialog has succeeded or been cancelled by the user.

Once the user has logged in successfully, your session object will have a session key from Facebook. The session key gives your application permission to call methods in the Facebook Platform API. If you want to be notified when login is successful, set a delegate on your session object which implements the FBSessionDelegate protocol. The most important delegate method to implement is FBSession:

- (void)session:(FBSession*)session didLogin:(FBUID)uid { NSLog(@"User with id %lld logged in.", uid); }


The session information will be stored on the iPhone disk in your application's preferences, so you won't have to ask the user to log in every time they use your application. After you've created your session object, call [session resume] to resume a previous session. If the session has expired or you have yet to create a session, it will return NO and you will have to ask your user to log in. Sessions expire after two hours of inactivity.

The user also can choose to be kept logged into your application when the user Connects to your application, in which case the session never expires.

To prompt your users to log in and out, use these Facebook Connect for iPhone Buttons. For usage guidelines, read the Platform Principles and Policies.

Logging Out

To log the user out and erase all traces of the session from disk, you can call [session logout].

Getting Extended Permissions

An extended permission allows a user to give consent to your application to perform more private actions on behalf of or to the user -- actions like updating the user's status, sending the user email, or accessing the user's information when the user isn't logged into your application. To ask your users for an extended permission, call FBPermissionDialog:

FBPermissionDialog* dialog = [[[FBPermissionDialog alloc] init] autorelease]; dialog.delegate = self; dialog.permission = @"status_update"; [dialog show];


If the user grants permission, the dialogDidSucceed delegate method gets called:

- (void)dialogDidSucceed:(FBDialog*)dialog { [self doSomethingExciting]; }


If the user decides not to grant permission, the dialogDidCancel delegate method gets called:

- (void)dialogDidCancel:(FBDialog*)dialog { }


When to Request Extended Permissions

If you request a permission that the user has already previously granted, then the FBPermissionDialog will close itself immediately upon opening, and the dialogDidSucceed delegate method will be called. Since this rapid open/close is somewhat of a jarring user experience, your application should only spawn an FBPermissionDialog for permissions that are not already granted. To know if a permission is already granted, you can call the Users.hasAppPermission API call. Ideally, though, your application should cache which permissions it has, so that it does not need to make an unnecessary roundtrip to Facebook's API servers before each use of an extended permission.

Another strategy for dealing with extended permissions is to have your application assume that the user has already granted the permission that it needs when making API calls. If your application does not have the permission, catch the error, spawn the FBPermissionDialog, and then try again.

Publishing Feed Stories to the Stream

Your users can share and distribute your application information on their Facebook profiles by publishing stories to the user's stream. To publish a story, use the FBStreamDialog class. This class pops up a Feed form that publishes a short story to a user's stream on the home page and on the Wall on the user's profile.

FBStreamDialog* dialog = [[[FBStreamDialog alloc] init] autorelease]; dialog.delegate = self; dialog.userMessagePrompt = @"Example prompt"; dialog.attachment = @"{\"name\":\"Facebook Connect for iPhone\"," "\"href\":\"http://developers.facebook.com/connect.php?tab=iphone\"," "\"caption\":\"Caption\",\"description\":\"Description\"," "\"media\":[{\"type\":\"image\"," "\"src\":\"http://img40.yfrog.com/img40/5914/iphoneconnectbtn.jpg\"," "\"href\":\"http://developers.facebook.com/connect.php?tab=iphone/\"}]," "\"properties\":{\"another link\":{\"text\":\"Facebook home page\",\"href\":\"http://www.facebook.com\"}}}"; // replace this with a friend's UID // dialog.targetId = @"999999"; [dialog show];

The attachment property is expected to be a JSON string using the format described here: Attachment (Streams).

You can promote your iPhone app in the stream by specifying your iPhone Application ID on the Advanced tab in the application settings editor. Users of the Facebook for iPhone app will see a link to your app in stream stories posted by your iPhone app, allowing the user to download your app.

Read more about Feed.

Using the API

You may choose to call the Facebook Platform API from your own servers or directly from the iPhone. If you want to call the API from your servers, you just need to get the sessionKey and sessionSecret properties from the session and send them back to your servers.

Whitelisting Your Servers

An iPhone can have any IP address, so if you're using a Server Whitelist, API calls from the iPhone will be rejected. To allow iPhones to securely bypass the whitelist, take the following steps:

  1. Go to the application settings editor, at http://www.facebook.com/developers/editapp.php?app_id=YOUR_APPLICATION_ID.
  2. Click the Advanced tab.
  3. Select Enable for Session Secret Whitelist Exception.
  4. Click Save Changes.

Note: You can use the Server Whitelist only if you create sessions using getSessionProxy, as described above. You cannot use the Server Whitelist if you are passing your application secret while creating the session, because the whitelist exception only applies to session secret-based sessions.

Calling the Platform API

Once you whitelist your servers, it's easy to call the Platform API directly from the iPhone. Facebook Connect for iPhone includes an Objective-C RPC bridge which lets you call API methods and asynchronously receive the response, parsed into Core Foundation objects. Here is a simple example:

- (void)getUserName { NSString* fql = @"select name from user where uid == 1234"; NSDictionary* params = [NSDictionary dictionaryWithObject:fql forKey:@"query"]; [[FBRequest requestWithDelegate:self] call:@"facebook.fql.query" params:params]; } - (void)request:(FBRequest*)request didLoad:(id)result { NSArray* users = result; NSDictionary* user = [users objectAtIndex:0]; NSString* name = [user objectForKey:@"name"]; NSLog(@"Query returned %@", name); }


Other examples of using the Facebook Connect API is to let the user change their status. This can be done using the following code in Objective-C:

-(void)setUsersStatus { NSString *statusString = exampleTextField.text; NSDictionary *params = [NSDictionary dictionaryWithObjectsAndKeys: statusString, @"status", @"true", @"status_includes_verb", nil]; [[FBRequest requestWithDelegate:self] call:@"facebook.Users.setStatus" params:params]; }

See Also

Retrieved from "http://wiki.developers.facebook.com/index.php/Facebook_Connect_for_iPhone"
reference