facebook_oauth

h1. Facebook OAuth Graph API client library for Ruby

h2. Install the gem

sudo gem install facebook_oauth

h2. Using the gem

To make authorized requests with the client library you'll need to "create a Facebook Application":http://www.facebook.com/developers/createapp.php.

See "http://facebook-oauth.heroku.com/":http://facebook-oauth.heroku.com/ for a full integration example.

h2. Authorized request example

To use the full power of the Facebook API you need to authorize your application and a valid Facebook user via OAuth. An example showing how to update the status of an authorized user is below.

Firstly we need to create an instance of the client with your application client credentials you have been given by Facebook when you set up your application.

client = FacebookOAuth::Client.new(
    :application_id => 'YOUR_APPLICATION_ID',
    :application_secret => 'YOUR_APP_SECRET_KEY',
    :callback => 'http://example.com/facebook/callback'
)

client.authorize_url
=> "https://graph.facebook.com/oauth/authorize?scope=SCOPE&client_id=ID&type=web_server&redirect_uri=CALLBACK"

In your application your user would be redirected to Facebook to authorize the application at this point. The code continues below assuming the user has authorized your application, facebook will return to your callback URL with a code parameter.

access_token = client.authorize(:code => code)

client.me.info # returns your user information

Now if you keep hold of the access_token.token (usually in the database) for this user you won't need to re-authorize them next time. When you create an instance of the client you can just pass in the access token that you have stored.

access_token = @user.access_token # assuming @user

client = FacebookOAuth::Client.new(
    :application_id => 'YOUR_APPLICATION_ID',
    :application_secret => 'YOUR_APP_SECRET_KEY',
    :token => access_token
)

client.me.info # returns your user information

h2. Supported objects

* Me (a special object that represents the current authorized user)

* Album
* Event
* Group
* Link
* Note
* Page
* Photo
* Post
* Status
* User
* Video

You can access any object listed above in the same way via the API. For example:

client.me.home    # the authorized users news feed
client.event('event_id').attending    # event attendees
client.group('group_id').members    # group members
client.photo('photo_id').comments  # comments on a photo

Check out the "Facebook API Reference":http://developers.facebook.com/docs/reference/api/ to see what methods are available.

h2. Publishing options

In order to publish content to a user you need to have the correct permissions. For example, to publish to a users wall you need the publish_stream permission. You specify the permissions you want to have for the authorizing user when you generate the authorize url like this:

client.authorize_url(:scope => 'publish_stream')

The scope is a comma-separated list of permissions. See the "Facebook Permissions Documentation":http://developers.facebook.com/docs/authentication/permissions for more information.

With the correct permissions you can now post to a users wall like this:

client.me.feed(:create, :message => 'Testing writing to your wall...')

Other examples include:

client.event('event_id').attending(:create) # the user is attending the event
client.post('post_id').comments(:create, :message => 'my comment') # comment on a post
client.user('user_id').albums(:create, :name => 'my album', :message => 'cool pictures') # create an album

For a full list of supported publishing objects and parameters check out the "Facebook API Documentation":http://developers.facebook.com/docs/api under "Publishing to Facebook."

NOTE: I still have to implement the upload a photo method. Also if you can think of a better syntax for the create methods let me know!