PhFacebook: easy-to-use MacOSX framework for the Facebook API
Summary
PhFacebook is an embeddable MacOSX framework to easily access Facebook's API.
-
Uses Facebook's new 'graph' API internally, handles OAuth in a WebView for you and returns JSON strings.
-
Comes with a sample application to show you how to use it.
-
Supports extended permissions.
-
Localized in English and French.
How-to-use
-
Set your Facebook Application Type
- Go to your Facebook application page.
- Select your application in the left-hand column (if you have more than one application).
- In the Summary section, note the "App ID/API Key". This is
YOUR_APPLICATION_ID
, used in section 3.
-
Build PhFacebook.framework
- Open "PhFacebook.xcodeproj" and click "Build".
- Select "PhFacebook.framework" in the Finder.
- Drag it to your "Frameworks" folder in your Project list and add it to the appropriate target.
- In your appropriate target, add a "Copy" build phase. Set its destination to "Frameworks".
- Drag "PhFacebook.framework" to this Copy build phase to ensure it is embedded in your application.
-
Prepare to use PhFacebook.framework
- Import <PhFacebook/PhFacebook> where appropriate.
- Create a new
PhFacebook*
object and set yourself as the delegate: PhFacebook* fb = [[PhFacebook alloc] initWithApplicationID: YOUR_APPLICATION_ID delegate: self]; - Implement the PhFacebookDelegate protocol: - (void) tokenResult: (NSDictionary*) result; - (void) requestResult: (NSDictionary*) result; @optional - (void) willShowUINotification: (PhFacebook*) sender; - (void) didDismissUI: (PhFacebook*) sender; These methods will be called by PhFacebook when an authorization token was requested or an API request was made. More information below.
- See the sample application if you have any issues.
-
Request an authorization token: [fb getAccessTokenForPermissions: [NSArray arrayWithObjects: @"read_stream", @"publish_stream", nil]];
- Just list the permissions you need in an array, or nil if you don't require special permissions.
- There is a list of permissions.
- Your delegate's
tokenResult:
will get called with a dictionary. If[[result valueForKey: @"valid"] boolValue]
is YES, the authorization request was successful. - If PhFacebook needs to display some UI (such as the Facebook Authentication dialog), your delegate's
willShowUINotification:
will get called. Take this opportunity to notify the user via a Dock bounce, for instance. - If the authorization was not successful, check
[result valueForKey: @"error"]
. - Note: the framework may put up an authorization window from Facebook. Subsequent requests are cached and/or hidden from the user as much as possible.
- Therefore: request a new token (and check its validity) for every series of operations. If some time elapses (for instance, you auto-check every hour), a new token is in order. It is cheap to call this method.
-
Make API requests
- You do not need to provide the URL or authorization token, PhFacebook takes care of that: [fb sendRequest: @"me/friends"];
- Your delegate's
requestResult:
will get called with a dictionary, whose "result" key's value is a JSON string from Facebook. - You can use a JSON parser to turn the string into an NSDictionary, for instance SBJSON.
- If the JSON string contains no data, check that you requested an authorization token with the correct permissions.
- The API is documented.
Notes
The sample application requires your Application ID to function properly. The first time you build the application, it will create a (non-versioned) file called
ApplicationID.h
. You must edit this file with your Application ID from this Facebook page before the sample app will build.
Tips and Tricks
- Embedding a framework is easier if you set up a common build folder in Xcode -> Preferences -> Building -> Customized location.
- Linking frameworks can sometimes be a black art. You may have to add
@loader_path/../Frameworks
to the "Runpath search paths" in Xcode (thanks to Oscar Del Ben for the tip). - You can
#define ALWAYS_SHOW_UI
in PhWebViewController.m to help you debug the framework, since by default the framework tries to hide UI as much as possible.