class Koala::Facebook::RealtimeUpdates

Attributes

app_access_token[R]

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.
app_id[R]

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.
secret[R]

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

meet_challenge(params, verify_token = nil) { |params| ... } click to toggle source

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
new(options = {}) click to toggle source

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

api() click to toggle source

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_subscriptions(options = {}) click to toggle source

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(object, fields, callback_url, verify_token, options = {}) click to toggle source

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
subscription_path() click to toggle source

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(object = nil, options = {}) click to toggle source

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
validate_update(body, headers) click to toggle source

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