mobileiq/facebook-ios-sdk

Facebook iOS SDK

This open source iOS library allows you to integrate Facebook into your iOS application include iPhone, iPad and iPod touch.

Except as otherwise noted, the Facebook iOS SDK is licensed under the Apache License, Version 2.0 (http://www.apache.org/licenses/LICENSE-2.0.html)

Getting Started

The SDK is lightweight and has no external dependencies. Getting started is quick and easy.

Install necessary packages

• Set up for iPhone development by following iPhone Dev Center Getting Started Documents.

• Install Git.

• Pull code down from github:

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

Create your own application

• Create a Facebook Application at: http://www.facebook.com/developers/createapp.php

• Adding Facebook to your Xcode project

  • Open src/facebook-ios-sdk.xcodeproj

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

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

  • Include the FBConnect headers in your code:

     #import "FBConnect/FBConnect.h"
    

  • You should now be able to compile your project successfully.

Usage

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

• Authorize users: prompt users to log in to facebook and grant access permission to your application.

User credentials are not handled by the iOS application in this SDK: authentication is done in an embedded webView using the OAuth 2.0 User-Agent flow to obtain an access token.

• Make API requests

Requests to the Facebook Graph and REST APIs are supported in this SDK. Authenticated requests are done over https using the OAuth access token.

• Display a Facebook dialog

The SDK supports several WebView html dialogs for user interactions, such as creating a wall post. This is intended to provided quick Facebook functionality without having to implement a native iOS UI and pass data to facebook directly though the APIs.

Authentication and Authorization

User login and application permission requests use the same method: authorize(). By default, if you pass an empty ''permissions'' parameter, then you will get access to the user's basic information., which includes their name, profile picture, list of friends and other general information. For more information, see http://developers.facebook.com/docs/authentication/.

If you pass in extra permissions in the permissions parameter (e.g. "publish_stream", "offline_access"), then the user will be prompted to grant these permissions. "offline_access" is particularly useful, as it avoids access expiration and ongoing prompts to the user for access. See http://developers.facebook.com/docs/authentication/permissions.

To authorize a user, the simplest usage is:

 facebook = [[Facebook alloc] init];
 [facebook authorize:appId permissions:permissions delegate:self];

One-Time Authentication

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 4's fast app switching. It works as follows:

If the app is running in iOS version 4 or greater, 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 iOS version 4 or greater 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 in iOS 3.x, 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.

Setting Up One-Time Authentication

For One-Time Authentication to work, you MUST do the following:

1. In your application's Info.plist file, add a new URL scheme. The URL scheme should be fb[your-app-id]. For example, if your Facebook application ID is 1234, the URL scheme should be 'fb1234'.

2. In your application's UIApplicationDelegate class, add the

• (BOOL)application:(UIApplication *)application handleOpenURL:(NSURL *)url

method if it doesn't exist already. In this method, call your application's Facebook object's handleOpenURL method, passing into it the url parameter.

See the sample applications for more specific code samples.

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 OAuth 2.0 token.

 [facebook logout:self]

Accessing the Graph API

The (http://developers.facebook.com/docs/api)[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

The FBRequestDelegate is an interface that handle the request response that your application should implement.

Note that the server response is in JSON string format. The SDK use a open source package json frame work (http://code.google.com/p/json-framework/) to parse the result. If there is error, it will call request:didFailWithError: function in the FBRequestDelegate. If it is succeed, it will call request:didLoad: function in the FBRequestDelegate. The result passed to the FBRequestDelegate can be an NSArray for multiple results or a NSDictionary for single result. i whose fields and values can be inspected and accessed. The sample implementation checks for a variety of error conditions and raises JSON or Facebook exceptions if the content is invalid or includes an error generated by the server. Advanced applications may wish to provide their own parsing and error handling.

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

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

User Interface Dialogs

This SDK provides a method for popping up a Facebook dialog. The currently supported dialogs are the login and permissions dialogs used in the authorization flow, and a "stream.publish" flow for making a wall post. The dialog require an action to perform, and a FBDialogDelegate interface for notification that must be implemented by the application. For example,

 NSMutableDictionary* params = [NSMutableDictionary dictionaryWithObjectsAndKeys: apiKey, @"api_key", nil];

 [facebook dialog: @"stream.publish" andParams: params andDelegate:self];

This allows you to provide basic Facebook functionality in your application with a singe line of code -- no need to build native dialogs, make API calls, or handle responses.

Error Handling

For Request and Dialog, errors are handled by FBRequestDelegate and FBDialogDelegate callback methods. Application can implement these interface to handle them.

Troubleshooting

: I get a ''missing client_id'' error. ; Read the setup instructions and make sure your application ID is set.