MiniFB is a small, lightweight Ruby library for interacting with the Facebook API.
Brought to you by:
Join our Discussion Group at: http://groups.google.com/group/mini_fb
There is a demo Rails app that uses mini_fb graph api at: http://github.com/appoxy/mini_fb_demo
gem install mini_fb
For an overview of what this is all about, see http://developers.facebook.com/docs/api.
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.
@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.
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)
my_query = "select uid,a,b,c from users where ...."
@res = MiniFB.fql(@access_token, my_query)
To enabled logging:
MiniFB.enable_logging
This API will probably go away at some point, so you should use the Graph API above in most cases.
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.
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}'}
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])
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
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
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.