PhFacebook: easy-to-use MacOSX framework for the Facebook API
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.
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.
- Open "PhFacebook.xcodeproj" and "Build for Archiving" in the Product -> Build menu. This should build both the Debug and Release version. If it does not, check your Build Schemes in Product -> Edit Scheme…
- Select "PhFacebook.framework" in the Finder. It should be in the "Release" folder; you probably don't want to embed the Debug version.
- Drag it to your "Frameworks" folder in your Project list and add it to the appropriate target.
- In your appropriate target, under "Build Settings", select "Runpath Search Paths" in the "Linking" category, and enter "@loader_path/../Frameworks" (without the quotes). This step is essential for linking, as the Framework is built with a "@rpath" search path, which will be replaced at runtime by your application.
- 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.
- Verify that you can build and run your application and there are no linker or runtime errors.
Prepare to use PhFacebook.framework
- Import 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.
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/../Frameworksto the "Runpath search paths" in Xcode (thanks to Oscar Del Ben for the tip).
- You can
#define ALWAYS_SHOW_UIin PhWebViewController.m to help you debug the framework, since by default the framework tries to hide UI as much as possible.