Facebook Connect for iPhone

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

Adding Connect to your Xcode project

To get started, you'll need to add Facebook for Connect for iPhone to your application's Xcode project like so:

1. Open the src/FBConnect.xcodeproj project file.

2. Drag the "FBConnect" group into your application's Xcode project.

3. 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.

4. 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. These objects represent the session of a user who has authenticated with your Facebook application. You should create only one session object at a time, and retain it for the lifetime of your application.

To create a session, you need to use your Facebook application's API key and secret:

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

If you do not want to store your API secret in the application, you can use another method which allows you to specify a URL instead which will be called to create a session:

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

This URL will be called with an HTTP GET request that includes an "auth_token" argument. You may use that token to call facebook.auth.getSession on your own servers. The response that your getSessionProxy should return is the same XML response that facebook.auth.getSession returned to your server.

Logging In

Once you have a session for your application you can ask the user to login. 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 show 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] init] autorelease];
[dialog show];

FBLoginDialog behaves similiarly to Apple's UIAlertView. It will take your user to facebook.com to 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 receive a session key from Facebook which gives it permission to call methods in the Facebok 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 this one:

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

The session information will be stored on disk in your application's preferences, so you won't have to ask the user to login every time. 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 login.

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

Extended Permissions

To ask your users for an extended permission, use the permission dialog like so:

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

If the user grants permission, this delegate methodwill be called:

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

If the user decides not to grant permission, this delegate method will be called:

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

For more information about extended permissions, see http://wiki.developers.facebook.com/index.php/Extended_permissions.

Publishing Feed Stories

To publish a story to your user's feed, use the stream dialog like so:

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: http://wiki.developers.facebook.com/index.php/Attachment_%28Streams%29

Using the API

You may choose to call the Facebook 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.

If you want to call the Facebook API directly from the iPhone, it's quite easy. 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);
}

For more information on the Facebook Connect program, visit the Facebook Connect wiki:

http://wiki.developers.facebook.com/index.php/Facebook_Connect