MiniFB - the simple miniature facebook library
MiniFB is a small, lightweight Ruby library for interacting with the Facebook API.
Support
Join our Discussion Group at: http://groups.google.com/group/mini_fb
Demo Rails Application
There is a demo Rails app that uses mini_fb graph api at: http://github.com/appoxy/mini_fb_demo
Installation
gem install mini_fb
Facebook Graph API
For an overview of what this is all about, see http://developers.facebook.com/docs/api.
Authentication
Facebook now uses Oauth 2 for authentication, but don't worry, this part is easy.
# Get your oauth url
@oauth_url = MiniFB.oauth_url(FB_APP_ID, # your Facebook App ID (NOT API_KEY)
"http://www.yoursite.com/sessions/create", # redirect url
:scope=>MiniFB.scopes.join(",")) # This asks for all permissions
# Have your users click on a link to @oauth_url
.....
# Then in your /sessions/create
access_token_hash = MiniFB.oauth_access_token(FB_APP_ID, "http://www.yoursite.com/sessions/create", FB_SECRET, params[:code])
@access_token = access_token_hash["access_token"]
# TODO: This is where you'd want to store the token in your database
# but for now, we'll just keep it in the cookie so we don't need a database
cookies[:access_token] = @access_token
That's it. You now need to hold onto this access_token. We've put it in a cookie for now, but you probably want to store it in your database or something.
General Use
@response_hash = MiniFB.get(@access_token, @id, @options = {})
It's very simple:
@id = {some ID of something in facebook} || "me"
@options:
type = {some facebook type like feed, friends, or photos}
version = {version of the graph api}. Example: "2.5"
fields = {array of fields to explicit fetch}
params = {optional params}
# @response_hash is a hash, but also allows object like syntax for instance, the following is true:
@response_hash["user"] == @response_hash.user
See http://developers.facebook.com/docs/api for the available types.
Posting Data to Facebook
Also pretty simple:
@id = {some ID of something in facebook}
@type = {some type of post like comments, likes, feed} # required here
@response_hash = MiniFB.post(@access_token, @id, :type=>@type)
FQL
my_query = "select uid,a,b,c from users where ...."
@res = MiniFB.fql(@access_token, my_query)
Logging
To enabled logging:
MiniFB.enable_logging
Original Facebook API
This API will probably go away at some point, so you should use the Graph API above in most cases.
General Usage
The most general case is to use MiniFB.call method:
user_hash = MiniFB.call(FB_API_KEY, FB_SECRET, "Users.getInfo", "session_key"=>@session_key, "uids"=>@uid, "fields"=>User.all_fields)
Which simply returns the parsed json response from Facebook.
Oauth 2.0 Authentication and Original Rest Api
You can use the Graph api Oauth 2.0 token with original api methods. BEWARE: This has only been tested against stream.publish at present.
MiniFB.rest(@access_token, "rest.api.method", options)
eg:
response = MiniFB.rest(@access_token, "stream.publish", :params => {
:uid => @user_id, :target_id => @target_user_id,
:message => "Hello other user!"
})
all responses will be json. In the instance of 'bad json' methods, the response will formatted {'response': '#{bad_response_string}'}
Some Higher Level Objects for Common Uses
Get a MiniFB::Session:
@fb = MiniFB::Session.new(FB_API_KEY, FB_SECRET, @fb_session, @fb_uid)
Then it makes it a bit easier to use call for a particular user/session.
response = @fb.call("stream.get")
With the session, you can then get the user information for the session/uid.
user = @fb.user
Then get info from the user:
first_name = user["first_name"]
Or profile photos:
photos = user.profile_photos
Or if you want other photos, try:
photos = @fb.photos("pids"=>[12343243,920382343,9208348])
Higher Level Objects with OAuth2
Get a MiniFB::OAuthSession with a Spanish locale:
@fb = MiniFB::OAuthSession.new(access_token, 'es_ES')
Using the session object to make requests:
@fb.get('117199051648010')
@fb.post('me', :type => :feed, :params => {
:message => "This is me from MiniFB"
})
@fb.fql('SELECT id FROM object_url WHERE url="http://www.imdb.com/title/tt1250777/"')
@fb.rest('notes.create', :params => {
:title => "ToDo", :content => "Try MiniFB"
})
Getting graph objects through the session:
@fb.me
@fb.me.name
@fb.me.connections
@fb.me.feed
@ssp = @fb.graph_object('117199051648010')
@ssp.mission
@ssp.photos
Facebook Connect
This is actually very easy, first follow these instructions: http://wiki.developers.facebook.com/index.php/Connect/Setting_Up_Your_Site
Then add the following script to the page where you put the login button so it looks like this:
<script>
function facebook_onlogin(){
document.location.href = "<%= url_for :action=>"fb_connect" %>";
}
</script>
<fb:login-button onlogin="facebook_onlogin();"></fb:login-button>
Define an fb_connect method in your login/sessions controller like so:
def fb_connect
@fb_info = MiniFB.parse_cookie_information(FB_APP_ID, cookies) # some users may have to use their API rather than the app. ID.
puts "uid=#{@fb_info['uid']}"
puts "session=#{@fb_info['session_key']}"
if MiniFB.verify_cookie_signature(FB_APP_ID, FB_SECRET, cookies)
# And here you would create the user if it doesn't already exist, then redirect them to wherever you want.
else
# The cookies may have been modified as the signature does not match
end
end
Photo Uploads
This is as simple as calling:
@fb.call("photos.upload", "filename"=>"<full path to file>")
The file_name parameter will be used as the file data.