Skip to content

Latest commit

 

History

History
77 lines (58 loc) · 4.48 KB

README.markdown

File metadata and controls

77 lines (58 loc) · 4.48 KB
Raw

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

  1. Set your Facebook Application Type

    • Go to your Facebook application page.
    • Select "Edit Settings".
    • In the Mobile section, set the Application Type to "Native application".

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

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

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

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