rfacebook 0.5.1 → 0.6.0

data/README

@@ -1,3 +1,78 @@
+============================== FACEBOOK RAILS CONTROLLER EXTENSIONS NOTES ==============================
+
+Rails Applications:
+
+First, set up your Facebook Developer account properly.  By properly,
+I mean that you need to set your callback URL to be the root of your
+Rails application.  For example:
+
+	Callback URL >>> http://www.mycrazywebsite.com/     ***NOTE: trailing slash is necessary
+	Canvas Page URL >>> http://apps.facebook.com/mycrazywebsite
+	
+Then, whenever a user visits
+	
+	http://apps.facebook.com/mycrazywebsite/someRailsController/someAction
+
+...the Facebook API will call:
+	
+	http://www.mycrazywebsite.com/someRailsController/someAction
+
+
+You can get this behavior by installing the new RFacebook gem. After
+installing the gem, make your ApplicationController look like this:
+
+>>>>>>>>>>>> require "facebook_rails_controller_extensions"
+>>>>>>>>>>>>
+>>>>>>>>>>>> class ApplicationController < ActionController::Base
+>>>>>>>>>>>>
+>>>>>>>>>>>>   # additions to integrate Facebook into controllers
+>>>>>>>>>>>>   include RFacebook::RailsControllerExtensions
+>>>>>>>>>>>>
+>>>>>>>>>>>>   def facebook_api_key
+>>>>>>>>>>>>     return "<YOUR API KEY HERE>"
+>>>>>>>>>>>>   end
+>>>>>>>>>>>>
+>>>>>>>>>>>>   def facebook_api_secret
+>>>>>>>>>>>>     return "<YOUR API SECRET HERE>"
+>>>>>>>>>>>>   end
+>>>>>>>>>>>>
+>>>>>>>>>>>> end
+
+You will have access to 2 new items in your controllers:
+
+(1) "fbsession"
+Contains a FacebookWebSession.  Will return false for "is_valid?" if you haven't forced the user to log in.
+
+
+(2) "fbparams"
+Contains all the params that are prefixed with "fb_sig_".  You shouldn't ever *really* need this, but its there just in case.
+
+
+And, you have a few new filters to try out:
+
+(1) require_facebook_login
+(2) require_facebook_install
+
+For example, one of my Rails controllers looks like this:
+
+>>>>>>>>>>>> class FacebookController < ApplicationController
+>>>>>>>>>>>>   
+>>>>>>>>>>>>   before_filter :require_facebook_install # require users to install the application (less intrusive is to require_facebook_login)
+>>>>>>>>>>>>   
+>>>>>>>>>>>>   def index
+>>>>>>>>>>>>     xml = fbsession.users_getInfo(:uids => [fbsession.session_user_id], :fields => ["first_name", "last_name"])
+>>>>>>>>>>>>     @firstName = xml.at("first_name").inner_html
+>>>>>>>>>>>>     @lastName = xml.at("last_name").inner_html
+>>>>>>>>>>>>   end
+>>>>>>>>>>>>   
+>>>>>>>>>>>>   
+>>>>>>>>>>>> end
+
+
+
+============================== FACEBOOK PLATFORM NOTES ==============================
+
+
 ============================== IMPORTANT NOTES ==============================
 
 

data/lib/facebook_desktop_session.rb

@@ -64,7 +64,7 @@ class FacebookDesktopSession < FacebookSession
     optionalHideCheckbox = (hidecheckbox == true) ? "&hide_checkbox=true" : ""
     
     # build and return URL
-    return "http://#{LOGIN_SERVER_BASE_URL}#{LOGIN_SERVER_PATH}?v=1.0&api_key=#{@api_key}&auth_token=#{@desktop_auth_token}#{optionalPopup}#{optionalNext}#{optionalSkipCookie}#{optionalHideCheckbox}"
+    return "http://#{WWW_SERVER_BASE_URL}#{WWW_PATH_LOGIN}?v=1.0&api_key=#{@api_key}&auth_token=#{@desktop_auth_token}#{optionalPopup}#{optionalNext}#{optionalSkipCookie}#{optionalHideCheckbox}"
   end
   
   
@@ -97,13 +97,21 @@ class FacebookDesktopSession < FacebookSession
     
     # determine the current user's id
     result = call_method("users.getLoggedInUser")
-    @session_uid = result.at("users_getLoggedInUser_response").inner_html
+    @session_user_id = result.at("users_getLoggedInUser_response").inner_html
   end
   
   def is_valid?
     return (is_activated? and !session_expired?)
   end
   
+  def session_user_id
+    return @session_user_id
+  end
+  
+  def session_key
+    return @session_key
+  end
+  
   protected
   
   def is_activated?
@@ -118,7 +126,7 @@ class FacebookDesktopSession < FacebookSession
   def activate_with_token(auth_token)
     result = call_method("auth.getSession", {:auth_token => auth_token}, true)
     if result != nil
-      @session_uid = result.at("uid").inner_html
+      @session_user_id = result.at("uid").inner_html
       @session_key = result.at("session_key").inner_html
       @session_secret = result.at("secret").inner_html
     end

data/lib/facebook_rails_controller_extensions.rb

@@ -0,0 +1,120 @@
+require "facebook_web_session"
+
+module RFacebook
+  
+  module RailsControllerExtensions
+    
+        
+    # SECTION: Exceptions
+    
+    class APIKeyNeededException < Exception; end
+    class APISecretNeededException < Exception; end
+    
+    # SECTION: Template Methods (must be implemented by concrete subclass)
+    
+    def facebook_api_key
+      raise APIKeyNeededException
+    end
+    
+    def facebook_api_secret
+      raise APISecretNeededException
+    end
+    
+    
+    
+    # SECTION: Required Methods
+    
+    def fbparams
+      
+      @fbparams ||= {};
+      
+      # try to get fbparams from the params hash
+      if (@fbparams.length <= 0)
+        @fbparams = fbsession.get_fb_sig_params(params)
+      end
+      
+      # else, try to get fbparams from the cookies hash
+      # TODO: we don't write anything into the cookie, so this is kind of pointless right now
+      if (@fbparams.length <= 0)
+        @fbparams = fbsession.get_fb_sig_params(cookies)
+      end
+      
+      return @fbparams
+      
+    end
+
+    def fbsession
+      
+      if !@fbsession
+        
+        # create a Facebook session that can be used by the controller
+        @fbsession = FacebookWebSession.new(facebook_api_key, facebook_api_secret)
+
+        # now we need to activate the session somehow.  If the signature parameters are bad, then we don't make the session
+        if fbparams
+          # these might be nil
+          facebookUid = fbparams["user"]
+          facebookSessionKey = fbparams["session_key"]
+          expirationTime = fbparams["expires"]
+        
+          # Method 1: user logged in and was redirected to our site (iframe/external)
+          if ( params["auth_token"] )
+            @fbsession.activate_with_token(params["auth_token"])
+          # Method 2: we have the user id and key from the fb_sig_ params
+          elsif (facebookUid and facebookSessionKey and expirationTime)
+            @fbsession.activate_with_previous_session(facebookSessionKey, facebookUid, expirationTime)
+          end  
+        end
+        
+      end
+      
+      return @fbsession
+      
+    end
+    
+    # SECTION: Helpful Methods
+    
+    def facebook_redirect_to(url)
+      
+      if (in_facebook_canvas? and !in_facebook_iframe?)
+        render :text => "<fb:redirect url=\"#{url}\" />"
+    
+      elsif url =~ /^https?:\/\/([^\/]*\.)?facebook\.com(:\d+)?/i # TODO: why doesn't this just check for iframe?
+        render :text => "<script type=\"text/javascript\">\ntop.location.href = \"#{url}\";\n</script>"
+        
+      else
+        redirect_to url
+        
+      end
+      
+    end
+    
+    def in_facebook_canvas?
+      return (fbparams["in_fbframe"] != nil)
+    end
+        
+    def in_facebook_iframe?
+      return (fbparams["in_iframe"] != nil)
+    end
+    
+    def require_facebook_login
+      sess = fbsession
+      if (sess and !sess.is_valid?)
+        if in_facebook_canvas?
+          render :text => "<fb:redirect url=\"#{sess.get_login_url(:canvas=>true)}\" />"
+        else
+          redirect_to sess.get_login_url
+        end
+      end
+    end
+    
+    def require_facebook_install
+      sess = fbsession
+      if (sess and !sess.is_valid? and in_facebook_canvas?)
+        render :text => "<fb:redirect url=\"#{sess.get_install_url(:canvas=>true)}\" />"
+      end
+    end
+    
+  end
+  
+end

data/lib/facebook_session.rb

@@ -39,14 +39,17 @@ require "hpricot"
 
 module RFacebook
 
-API_SERVER_BASE_URL      = "api.facebook.com"
-LOGIN_SERVER_BASE_URL    = "www.facebook.com"
-API_SERVER_PATH          = "/restserver.php"
-LOGIN_SERVER_PATH        = "/login.php"
+API_SERVER_BASE_URL       = "api.f8.facebook.com"
+API_PATH_REST             = "/restserver.php"
+
+WWW_SERVER_BASE_URL       = "www.f8.facebook.com"
+WWW_PATH_LOGIN            = "/login.php"
+WWW_PATH_ADD              = "/add.php"
+WWW_PATH_INSTALL          = "/install.php"
 
 class FacebookSession
   
-  attr_reader :session_uid, :session_key
+  # error handling accessors
   attr_reader :last_call_was_successful, :last_error
   attr_writer :suppress_exceptions
   
@@ -73,7 +76,7 @@ class FacebookSession
     
     # calculated parameters
     @api_server_base_url = API_SERVER_BASE_URL
-    @api_server_path = API_SERVER_PATH
+    @api_server_path = API_PATH_REST
         
     # optional parameters
     @suppress_exceptions = suppress_exceptions
@@ -83,37 +86,42 @@ class FacebookSession
     @last_error = nil
     @session_expired = false
     
-    # virtual members (subclasses will set these)
-    @session_uid = nil
-    @session_key = nil
-    
   end
   
   def session_expired?
     return (@session_expired == true)
   end
-    
-  protected
-  
-  # SECTION: Protected Abstract Interface
+
+  # SECTION: Public Abstract Interface
+
+  def is_valid?
+    raise Exception
+  end
   
-  def get_secret(params)
+  def session_key
     raise Exception
   end
   
-  def init_with_token(auth_token)
+  def session_user_id
     raise Exception
   end
   
-  def session_key=(key)
+  def session_expires
     raise Exception
   end
   
-  def is_activated?
+  def session_uid # deprecated
+    return session_user_id
+  end
+  
+  # SECTION: Protected Abstract Interface
+  protected
+  
+  def get_secret(params)
     raise Exception
   end
   
-  def is_valid?
+  def is_activated?
     raise Exception
   end
   
@@ -152,7 +160,7 @@ class FacebookSession
     params[:v] = "1.0"
     
     if (method != "auth.getSession" and method != "auth.createToken")
-      params[:session_key] = @session_key
+      params[:session_key] = session_key
       params[:call_id] = Time.now.to_f.to_s
     end
     
@@ -175,7 +183,7 @@ class FacebookSession
       @last_call_was_successful = false
       code = xml.at("error_code").inner_html
       msg = xml.at("error_msg").inner_html
-      @last_error = "ERROR #{code}: #{msg} (#{method}, #{params})"
+      @last_error = "ERROR #{code}: #{msg} (#{method.inspect}, #{params.inspect})"
       @last_error_code = code
       
       # check to see if this error was an expired session error
@@ -227,16 +235,19 @@ class FacebookSession
   # Function: param_signature
   #   Generates a param_signature for a call to the API, per the spec on Facebook
   #   see: <http://developers.facebook.com/documentation.php?v=1.0&doc=auth>
-  def param_signature(params)
+  def param_signature(params)    
+    return generate_signature(params, get_secret(params));
+  end
+  
+  def generate_signature(hash, secret)
     
     args = []
-    params.each do |k,v|
+    hash.each do |k,v|
       args << "#{k}=#{v}"
     end
-    sorted_array = args.sort
-    request_str = sorted_array.join("")
-    param_signature = Digest::MD5.hexdigest("#{request_str}#{get_secret(params)}") # uses Template method get_secret
-    return param_signature
+    sortedArray = args.sort
+    requestStr = sortedArray.join("")
+    return Digest::MD5.hexdigest("#{requestStr}#{secret}")
     
   end
 

data/lib/facebook_web_session.rb

@@ -38,77 +38,169 @@ module RFacebook
 
 class FacebookWebSession < FacebookSession
   
-  # Function: get_login_url
-  #   Gets the authentication URL
-  #
-  # Parameters:
-  #   options.next          - the page to redirect to after login
-  #   options.popup         - boolean, whether or not to use the popup style (defaults to true)
-  #   options.skipcookie    - boolean, whether to force new Facebook login (defaults to false)
-  #   options.hidecheckbox  - boolean, whether to show the "infinite session" option checkbox
-  def get_login_url(options={})
-    # options
-    path_next = options[:next] ||= nil
-    popup = (options[:popup] == nil) ? true : false
-    skipcookie = (options[:skipcookie] == nil) ? false : true
-    hidecheckbox = (options[:hidecheckbox] == nil) ? false : true
+    # SECTION: Properties
     
-    # get some extra portions of the URL
-    optionalNext = (path_next == nil) ? "" : "&next=#{CGI.escape(path_next.to_s)}"
-    optionalPopup = (popup == true) ? "&popup=true" : ""
-    optionalSkipCookie = (skipcookie == true) ? "&skipcookie=true" : ""
-    optionalHideCheckbox = (hidecheckbox == true) ? "&hide_checkbox=true" : ""
-    
-    # build and return URL
-    return "http://#{LOGIN_SERVER_BASE_URL}#{LOGIN_SERVER_PATH}?v=1.0&api_key=#{@api_key}#{optionalPopup}#{optionalNext}#{optionalSkipCookie}#{optionalHideCheckbox}"
-  end
+    def session_key
+      return @session_key
+    end
   
-  # Function: activate_with_token
-  #   Gets the session information available after current user logs in.
-  # 
-  # Parameters:
-  #   auth_token    - string token passed back by the callback URL
-  def activate_with_token(auth_token)
-    result = call_method("auth.getSession", {:auth_token => auth_token})
-    if result != nil
-      @session_uid = result.at("uid").inner_html
-      @session_key = result.at("session_key").inner_html
+    def session_user_id
+      return @session_uid
     end
-  end
   
-  # Function: activate_with_previous_session
-  #   Sets the session key directly (for example, if you have an infinite session key)
-  # 
-  # Parameters:
-  #   key    - the session key to use
-  def activate_with_previous_session(key)
-    # set the session key
-    @session_key = key
+    def session_expires
+      return @session_expires
+    end
     
-    # determine the current user's id
-    result = call_method("users.getLoggedInUser")
-    @session_uid = result.at("users_getLoggedInUser_response").inner_html
-  end
+    # SECTION: URL Getters
+    
+    # Function: get_login_url
+    #   Gets the authentication URL
+    #
+    # Parameters:
+    #   options.next          - the page to redirect to after login
+    #   options.popup         - boolean, whether or not to use the popup style (defaults to true)
+    #   options.skipcookie    - boolean, whether to force new Facebook login (defaults to false)
+    #   options.hidecheckbox  - boolean, whether to show the "infinite session" option checkbox
+    def get_login_url(options={})
+
+      # handle options
+      nextPage = options[:next] ||= nil
+      popup = (options[:popup] == nil) ? false : true
+      skipcookie = (options[:skipcookie] == nil) ? false : true
+      hidecheckbox = (options[:hidecheckbox] == nil) ? false : true
+      frame = (options[:frame] == nil) ? false : true
+      canvas = (options[:canvas] == nil) ? false : true
+    
+      # url pieces
+      optionalNext = (nextPage == nil) ? "" : "&next=#{CGI.escape(nextPage.to_s)}"
+      optionalPopup = (popup == true) ? "&popup=true" : ""
+      optionalSkipCookie = (skipcookie == true) ? "&skipcookie=true" : ""
+      optionalHideCheckbox = (hidecheckbox == true) ? "&hide_checkbox=true" : ""
+      optionalFrame = (frame == true) ? "&fbframe=true" : ""
+      optionalCanvas = (canvas == true) ? "&canvas=true" : ""
+    
+      # build and return URL
+      return "http://#{WWW_SERVER_BASE_URL}#{WWW_PATH_LOGIN}?v=1.0&api_key=#{@api_key}#{optionalPopup}#{optionalNext}#{optionalSkipCookie}#{optionalHideCheckbox}#{optionalFrame}#{optionalCanvas}"
+    
+    end
+    
+    def get_install_url(options={})
+    
+      # handle options
+      nextPage = options[:next] ||= nil
+    
+      # url pieces
+      optionalNext = (nextPage == nil) ? "" : "&next=#{CGI.escape(nextPage.to_s)}"
+    
+      # build and return URL
+      return "http:/#{WWW_SERVER_BASE_URL}#{WWW_PATH_INSTALL}?api_key=#{@api_key}#{optionalNext}"
+    
+    end
   
-  def is_valid?
-    return (is_activated? and !session_expired?)
-  end
 
-  protected
+    # SECTION: Callback Verification Helpers
+    
+    def get_fb_sig_params(originalParams)
+            
+      # setup
+      timeout = 48*3600
+      namespace = "fb_sig"
+      prefix = "#{namespace}_"
+      
+      # get the params prefixed by "fb_sig_" (and remove the prefix)
+      sigParams = {}
+      originalParams.each do |k,v|
+        oldLen = k.length
+        newK = k.sub(prefix, "")
+        if oldLen != newK.length
+          sigParams[newK] = v
+        end
+      end
+      
+      # handle invalidation
+      if (timeout and (sigParams["time"].nil? or (Time.now.to_i - sigParams["time"].to_i > timeout.to_i)))
+        # invalidate if the timeout has been reached
+        sigParams = {}
+      end
+      
+      if !sig_params_valid?(sigParams, originalParams[namespace])
+        # invalidate if the signatures don't match
+        sigParams = {}
+      end
+      
+      return sigParams
+      
+    end
   
-  def is_activated?
-    return (@session_key != nil)
-  end
   
-  # Function: get_secret
-  #   Template method, used by super::signature to generate a signature
-  def get_secret(params)
+  
+    # SECTION: Session Activation
+  
+    # Function: activate_with_token
+    #   Gets the session information available after current user logs in.
+    # 
+    # Parameters:
+    #   auth_token    - string token passed back by the callback URL
+    def activate_with_token(auth_token)
+      result = call_method("auth.getSession", {:auth_token => auth_token})
+      if result != nil
+        @session_uid = result.at("uid").inner_html
+        @session_key = result.at("session_key").inner_html
+        @session_expires = result.at("expires").inner_html
+      end
+    end
+  
+    # Function: activate_with_previous_session
+    #   Sets the session key directly (for example, if you have an infinite session key)
+    # 
+    # Parameters:
+    #   key    - the session key to use
+    def activate_with_previous_session(key, uid=nil, expires=nil)
+      
+      # TODO: what is a good way to handle expiration?
+      #       low priority since the API will give an error code for me...
+      
+      # set the session key
+      @session_key = key
     
-    return @api_secret
+      # determine the current user's id
+      if uid
+        @session_uid = uid
+      else
+        result = call_method("users.getLoggedInUser")
+        @session_uid = result.at("users_getLoggedInUser_response").inner_html
+      end
+      
+    end
+  
+    def is_valid?
+      return (is_activated? and !session_expired?)
+    end
+  
+  
+  
+  
+  
+  
+    # SECTION: Protected methods
+    protected
+  
+    def is_activated?
+      return (@session_key != nil)
+    end
+  
+    # Function: get_secret
+    #   Template method, used by super::signature to generate a signature
+    def get_secret(params)
+      return @api_secret
+    end
     
-  end
+    def sig_params_valid?(sigParams, expectedSig)
+      return (sigParams and expectedSig and generate_signature(sigParams, @api_secret) == expectedSig)
+    end
   
-end
+  end
 
 
 

metadata

@@ -1,11 +1,11 @@
 --- !ruby/object:Gem::Specification 
-rubygems_version: 0.9.0
+rubygems_version: 0.9.1
 specification_version: 1
 name: rfacebook
 version: !ruby/object:Gem::Version 
-  version: 0.5.1
-date: 2007-05-08 00:00:00 -04:00
-summary: A Ruby interface to the Facebook API v1.0+
+  version: 0.6.0
+date: 2007-05-29 00:00:00 -07:00
+summary: A Ruby interface to the Facebook API v1.0+.  Supports the new features from F8.
 require_paths: 
 - lib
 email: matt@livelearncode.com
@@ -30,6 +30,7 @@ authors:
 - Matt Pizzimenti
 files: 
 - lib/facebook_desktop_session.rb
+- lib/facebook_rails_controller_extensions.rb
 - lib/facebook_session.rb
 - lib/facebook_web_session.rb
 - README