Facebook Connect for iPhone
Objective-C C++
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
samples/Connect
src
.gitignore
README.mdown

README.mdown

Facebook Connect for iPhone

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

Integrating Connect into your project

Facebook Connect is compiled as a static library, and the easiest way to add it to your project is to use Xcode's "dependent project" facilities. Here is how:

  1. Clone the repository and make sure you store it in a permanent place, because Xcode will need to reference the files every time you compile your project.
  2. Drag and drop the "FBConnect.xcodeproj" file under "facebook-iphone-sdk/src" onto the root of your Xcode project's "Groups and Files" sidebar.
  3. A dialog will appear -- make sure "Copy items" is unchecked and "Reference Type" is "Relative to Project" before clicking "Add".
  4. Link the FBConnect static library to your project:
    • Doubleclick the "FBConnect.xcodeproj" item that has just been added to the sidebar
    • Go to the "Details" table and you will see a single item: libFBConnect.a.
    • Check the checkbox on the far right of libFBConnect.a.
  5. Add FBConnect as a dependency of your project, so Xcode compiles it whenever you compile your project:
    • Expand the "Targets" section of the sidebar and double-click your application's target.
    • Go to the "General" tab and you will see a "Direct Dependencies" section.
    • Click the "+" button, select "FBConnect", and click "Add Target".
  6. Tell your project where to find the FBConnect headers:
    • Open your "Project Settings" and go to the "Build" tab.
    • Look for "Header Search Paths" and doubleclick it.
    • Add the relative path from your project's directory to the "facebook-iphone-sdk/src" directory.
  7. While you are in Project Settings, go to "Other Linker Flags" under the "Linker" section, and add "-ObjC" and "-all_load" to the list of flags.
  8. You're ready to go. Just #import "FBConnect/FBConnect.h" anywhere you want to use FBConnect classes in your project.

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