FbGraph

A full-stack Facebook Graph API wrapper in Ruby.

<img src=“https://secure.travis-ci.org/nov/fb_graph.png” />

This gem is deprecated

FbGraph is basically developed for Graph API v1.0, and could be buggy with v2.+.

Since Graph API v1.0 is shut down on 2014/04/30, this gem is also deprecated.

Please use fb_graph2 gem instead. github.com/nov/fb_graph2

Installation

geminstallfb_graph

Resources

• View Source on GitHub (github.com/nov/fb_graph)

• Report Issues on GitHub (github.com/nov/fb_graph/issues)

• Subscribe Update Info (www.facebook.com/FbGraph)

• Q&A on Google Groups (groups.google.com/group/fb_graph)

Examples

Now FbGraph supports all objects listed here: developers.facebook.com/docs/reference/api/ Almost all connections　for each object are also supported. (“attachments” and “shares” connections of message object are not supported yet)

You can also play with a Rails sample app here. fbgraphsample.heroku.com/

See GitHub wiki for more examples. github.com/nov/fb_graph/wiki

GET

Basic Objects

user = FbGraph::User.me(ACCESS_TOKEN)
user = FbGraph::User.fetch('matake')
user.name # => 'Nov Matake'
user.picture # => 'https://graph.facebook.com/matake/picture'
# fb_graph doesn't access to Graph API until you call "fetch"
user = FbGraph::User.new('matake', :access_token => YOUR_ACCESS_TOKEN)
user.identifier # => "matake"
user.name # => nil
user.link # => nil
user = user.fetch
user.name # => "Nov Matake"
user.description # => "http://www.facebook.com/matake"
page = FbGraph::Page.fetch('smartfmteam')
page.name # => 'smart.fm'
page.picture # => 'https://graph.facebook.com/smart.fm/picture'
:

Connections

# Public connections
user = FbGraph::User.fetch('matake')
user.feed
user.posts
user.friends
user.tagged
user.family
:
# Private connections requires "access_token"
FbGraph::User.new('matake').friends # => raise FbGraph::Unauthorized
user = FbGraph::User.fetch('matake', :access_token => ACCESS_TOKEN)
user.albums
user.events
user.friends
user.likes
:
# "home" connection is only available for "me"
me = User.new('me', :access_token => ACCESS_TOKEN)
me.home
:

By default, FbGraph will only return the default fields. In order to get a non-default field, you have to supply the connect with an optional hash specifying the field. An example for events:

user.events({:fields=>"owner,name,description,picture"}) # { and } optional

An overview of which fields you can include in the graph API can be found at developers.facebook.com/docs/reference/api/, which has a description of the specific objects fields in the sidebar under “Objects”.

Search

# all objectsFbGraph::Searchable.search("FbGraph") # => Array of Hash# specify typeFbGraph::Page.search("FbGraph") # => Array of FbGraph::PageFbGraph::User.search("matake", :access_token=>ACCESS_TOKEN) # => Array of FbGraph::User

Pagination

# collectionuser = FbGraph::User.new('matake', :access_token=>ACCESS_TOKEN)
likes = user.likes# => Array of FbGraph::Likelikes.next# => Array of FbGraph::Like (next page)likes.previous# => Array of FbGraph::Like (previous page)likes.collection.next# => Hash for pagination options (ex. {"limit"=>"25", "until"=>"2010-08-08T03:17:21+0000"})likes.collection.previous# => Hash for pagination options (ex. {"limit"=>"25", "since"=>"2010-08-08T06:28:20+0000"})user.likes(likes.collection.next) # => same with likes.nextuser.likes(likes.collection.previous) # => same with likes.previous# search resultsresults = FbGraph::Page.search("FbGraph") # => Array of FbGraph::Pageresults.next# => Array of FbGraph::Page (next page)results.previous# => Array of FbGraph::Page (next page)results.klass# => FbGraph::Pageresults.collection.next# => Hash for pagination options (ex. {"limit"=>"25", "until"=>"2010-08-08T03:17:21+0000"})results.collection.previous# => Hash for pagination options (ex. {"limit"=>"25", "since"=>"2010-08-08T06:28:20+0000"})results.klass.search(results.query, results.collection.next) # => same with results.nextresults.klass.search(results.query, results.collection.previous) # => same with results.previous

POST

Update status (wall post)

me = FbGraph::User.me(ACCESS_TOKEN)
me.feed!(
:message=>'Updating via FbGraph',
:picture=>'https://graph.facebook.com/matake/picture',
:link=>'https://github.com/nov/fb_graph',
:name=>'FbGraph',
:description=>'A Ruby wrapper for Facebook Graph API'
)

Post a like/comment to a post

post = FbGraph::Page.new(117513961602338).feed.firstbool = post.like!(
:access_token=>ACCESS_TOKEN
)
comment = post.comment!(
:access_token=>ACCESS_TOKEN,
:message=>'Hey, I\'m testing you!'
)

Post a note

page = FbGraph::Page.new(117513961602338)
note = page.note!(
:access_token=>ACCESS_TOKEN,
:subject=>'testing',
:message=>'Hey, I\'m testing you!'
)

Post a link

me = FbGraph::User.me(ACCESS_TOKEN)
link = me.link!(
:link=>'https://github.com/nov/fb_graph',
:message=>'A Ruby wrapper for Facebook Graph API.'
)

Create Event, respond to it

me = FbGraph::User.me(ACCESS_TOKEN)
event = me.event!(
:name=>'FbGraph test event',
:start_time=>1.week.from_now,
:end_time=>2.week.from_now
)
bool = event.attending!(
:access_token=>ACCESS_TOKEN
)
bool = event.maybe!(
:access_token=>ACCESS_TOKEN
)
bool = event.declined!(
:access_token=>ACCESS_TOKEN
)

Create an album

me = FbGraph::User.me(ACCESS_TOKEN)
album = me.album!(
:name=>'FbGraph test',
:message=>'test test test'
) # => now facebook Graph API returns weird response for this call

Upload a photo to an album

me = FbGraph::User.me(ACCESS_TOKEN)
album = me.albums.firstalbum.photo!(
:access_token=>ACCESS_TOKEN,
:source=>File.new('/Users/nov/Desktop/nov.gif', 'rb'), # 'rb' is needed only on windows:message=>'Hello, where is photo?'
)

DELETE

Delete an object

post = FbGraph::Page.new(117513961602338).feed.firstbool = post.like!(
:access_token=>ACCESS_TOKEN
)
comment = post.comment!(
:access_token=>ACCESS_TOKEN,
:message=>'Hey, I\'m testing you!'
)
comment.destroy(:access_token=>ACCESS_TOKEN)
post.unlike!(:access_token=>ACCESS_TOKEN)
post.destroy(:access_token=>ACCESS_TOKEN)

Authentication

Both Facebook JavaScript SDK and normal OAuth2 flow are supported. Below I show simple sample code. You can also see github.com/nov/fb_graph_sample for more details Rails3 sample application.

In addition, if you are migrating an application that uses old-style session keys you can exchange the keys for access tokens. See more here: developers.facebook.com/docs/authentication/fb_sig/

JavaScript SDK

fb_auth = FbGraph::Auth.new(YOUR_APP_ID, YOUR_APPLICATION_SECRET)
fb_auth.client# => Rack::OAuth2::Client# get Facebook's auth cookie in advance using their JS SDKfb_auth.from_cookie(cookies)
fb_auth.access_token# => Rack::OAuth2::AccessTokenfb_auth.user# => FbGraph::User (only basic attributes)fb_auth.user.fetch# => fetch more details

Normal OAuth2 Flow

# setup clientclient = fb_auth.clientclient.redirect_uri = "http://your.client.com/facebook/callback"# redirect user to facebookredirect_toclient.authorization_uri(
:scope=> [:email, :read_stream, :offline_access]
)
# in callbackclient.authorization_code = params[:code]
access_token = client.access_token!:client_auth_body# => Rack::OAuth2::AccessTokenFbGraph::User.me(access_token).fetch# => FbGraph::User

Extend Access Token Lifetime

# setup clientfb_auth = FbGraph::Auth.new(YOUR_APP_ID, YOUR_APPLICATION_SECRET)
fb_auth.exchange_token!'short-life-access-token'fb_auth.access_token# => Rack::OAuth2::AccessToken

Analytics

app = FbGraph::Application.new(YOUR_APP_ID, :secret=>YOUR_APPLICATION_SECRET)
app.insights# => Array of FbGraph::Insight

Test User

Not tested well yet. Sample is here. gist.github.com/752974

FQL

Not tested well yet. Sample is here. gist.github.com/752914

More Examples?

See GitHub wiki for more examples. github.com/nov/fb_graph/wiki

Note on Patches/Pull Requests

• Fork the project.

• Make your feature addition or bug fix.

• Add tests for it. This is important so I don’t break it in a future version unintentionally.

• Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)

• Send me a pull request. Bonus points for topic branches.

Copyright

Copyright © 2010 nov matake. See LICENSE for details.