class Koala::Facebook::RealtimeUpdates
Attributes
Manage realtime callbacks for changes to users' information. See developers.facebook.com/docs/reference/api/realtime.
@note: to subscribe to real-time updates, you must have an application access token
or provide the app secret when initializing your RealtimeUpdates object.
Manage realtime callbacks for changes to users' information. See developers.facebook.com/docs/reference/api/realtime.
@note: to subscribe to real-time updates, you must have an application access token
or provide the app secret when initializing your RealtimeUpdates object.
Manage realtime callbacks for changes to users' information. See developers.facebook.com/docs/reference/api/realtime.
@note: to subscribe to real-time updates, you must have an application access token
or provide the app secret when initializing your RealtimeUpdates object.
Public Class Methods
As a security measure (to prevent DDoS attacks), Facebook
sends a verification request to your server after you request a subscription. This method parses the challenge params and makes sure the call is legitimate.
@param params the request parameters sent by Facebook
. (You can pass in a Rails params hash.) @param verify_token the verify token sent in the {#subscribe subscription request}, if you provided one
@yield verify_token if you need to compute the verification token
(for instance, if your callback URL includes a record ID, which you look up and use to calculate a hash), you can pass meet_challenge a block, which will receive the verify_token received back from Facebook.
@return the challenge string to be sent back to Facebook
, or false if the request is invalid.
# File lib/koala/realtime_updates.rb 103 def self.meet_challenge(params, verify_token = nil, &verification_block) 104 if params["hub.mode"] == "subscribe" && 105 # you can make sure this is legitimate through two ways 106 # if your store the token across the calls, you can pass in the token value 107 # and we'll make sure it matches 108 ((verify_token && params["hub.verify_token"] == verify_token) || 109 # alternately, if you sent a specially-constructed value (such as a hash of various secret values) 110 # you can pass in a block, which we'll call with the verify_token sent by Facebook 111 # if it's legit, return anything that evaluates to true; otherwise, return nil or false 112 (verification_block && yield(params["hub.verify_token"]))) 113 params["hub.challenge"] 114 else 115 false 116 end 117 end
Create a new RealtimeUpdates
instance. If you don't have your app's access token, provide the app's secret and Koala
will make a request to Facebook
for the appropriate token.
@param options initialization options. @option options :app_id the application's ID. @option options :app_access_token an application access token, if known. @option options :secret the application's secret.
@raise ArgumentError if the application ID and one of the app access token or the secret are not provided.
# File lib/koala/realtime_updates.rb 22 def initialize(options = {}) 23 @app_id = options[:app_id] || Koala.config.app_id 24 @app_access_token = options[:app_access_token] || Koala.config.app_access_token 25 @secret = options[:secret] || Koala.config.app_secret 26 unless @app_id && (@app_access_token || @secret) # make sure we have what we need 27 raise ArgumentError, "Initialize must receive a hash with :app_id and either :app_access_token or :secret! (received #{options.inspect})" 28 end 29 end
Public Instance Methods
The application API
interface used to communicate with Facebook
. @return [Koala::Facebook::API]
# File lib/koala/realtime_updates.rb 40 def api 41 # Only instantiate the API if needed. validate_update doesn't require it, so we shouldn't 42 # make an unnecessary request to get the app_access_token. 43 @api ||= API.new(app_access_token) 44 end
List all active subscriptions for this application.
@param options (see Koala::HTTPService.make_request
)
@return [Array] a list of active subscriptions
# File lib/koala/realtime_updates.rb 86 def list_subscriptions(options = {}) 87 api.graph_call(subscription_path, {}, "get", options) 88 end
Subscribe to realtime updates for certain fields on a given object (user, page, etc.). See {developers.facebook.com/docs/reference/api/realtime the realtime updates documentation} for more information on what objects and fields you can register for.
@note Your callback_url must be set up to handle the verification request or the subscription will not be set up.
@param object a Facebook
ID (name or number) @param fields the fields you want your app to be updated about @param callback_url the URL Facebook
should ping when an update is available @param verify_token a token included in the verification request, allowing you to ensure the call is genuine
(see the docs for more information)
@param options (see Koala::HTTPService.make_request
)
@raise A subclass of Koala::Facebook::APIError
if the subscription request failed.
# File lib/koala/realtime_updates.rb 60 def subscribe(object, fields, callback_url, verify_token, options = {}) 61 args = { 62 :object => object, 63 :fields => fields, 64 :callback_url => callback_url, 65 }.merge(verify_token ? {:verify_token => verify_token} : {}) 66 # a subscription is a success if Facebook returns a 200 (after hitting your server for verification) 67 api.graph_call(subscription_path, args, 'post', options) 68 end
The Facebook
subscription management URL for your application.
# File lib/koala/realtime_updates.rb 146 def subscription_path 147 @subscription_path ||= "#{@app_id}/subscriptions" 148 end
Unsubscribe from updates for a particular object or from updates.
@param object the object whose subscriptions to delete.
If no object is provided, all subscriptions will be removed.
@param options (see Koala::HTTPService.make_request
)
@raise A subclass of Koala::Facebook::APIError
if the subscription request failed.
# File lib/koala/realtime_updates.rb 77 def unsubscribe(object = nil, options = {}) 78 api.graph_call(subscription_path, object ? {:object => object} : {}, "delete", options) 79 end
Public: As a security measure, all updates from facebook are signed using X-Hub-Signature: sha1=XXXX where XXX is the sha1 of the json payload using your application secret as the key.
Example:
# in Rails controller # @oauth being a previously defined Koala::Facebook::OAuth instance def receive_update if @oauth.validate_update(request.body, headers) ... end end
# File lib/koala/realtime_updates.rb 131 def validate_update(body, headers) 132 unless @secret 133 raise AppSecretNotDefinedError, "You must init RealtimeUpdates with your app secret in order to validate updates" 134 end 135 136 request_signature = headers['X-Hub-Signature'] || headers['HTTP_X_HUB_SIGNATURE'] 137 return unless request_signature 138 139 signature_parts = request_signature.split("sha1=") 140 request_signature = signature_parts[1] 141 calculated_signature = OpenSSL::HMAC.hexdigest('sha1', @secret, body) 142 calculated_signature == request_signature 143 end