Class: Facebooker::Session

Inherits:
Object
  • Object
show all
Defined in:
lib/facebooker/session.rb

Direct Known Subclasses

CanvasSession, Desktop

Defined Under Namespace

Classes: AlbumIsFull, BlankFeedTitle, CallOutOfOrder, ConfigurationMissing, Desktop, ExtendedPermissionRequired, FQLFieldDoesNotExist, FQLFunctionDoesNotExist, FQLParseError, FQLStatementNotIndexable, FQLTableDoesNotExist, FQLWrongNumberArgumentsPassedToFunction, FeedBodyDataInvalid, FeedBodyLengthTooLong, FeedBodyTemplateInvalid, FeedMarkupInvalid, FeedPhotosNotRetrieved, FeedTargetIdsInvalid, FeedTitleDataInvalid, FeedTitleTemplateInvalid, HostNotAllowed, IncorrectSignature, InvalidAPIKey, InvalidAlbumId, InvalidFeedPhotoLink, InvalidFeedPhotoSource, InvalidFeedTitleLength, InvalidFeedTitleLink, InvalidFeedTitleName, InvalidFriendList, MaxRequestsDepleted, MissingOrInvalidImageFile, MissingOrInvalidParameter, ServiceUnavailable, SessionExpired, SignatureTooOld, TemplateBundleInvalid, TemplateDataMissingRequiredTokens, TooManyUnapprovedPhotosPending, TooManyUserActionCalls, TooManyUserCalls, UnknownError, UserRegistrationFailed

Constant Summary collapse

API_SERVER_BASE_URL = 
ENV["FACEBOOKER_API"] == "new" ? "api.new.facebook.com" : "api.facebook.com"
API_PATH_REST = 
"/restserver.php"
WWW_SERVER_BASE_URL = 
ENV["FACEBOOKER_API"] == "new" ? "www.new.facebook.com" : "www.facebook.com"
WWW_PATH_LOGIN = 
"/login.php"
WWW_PATH_ADD = 
"/add.php"
WWW_PATH_INSTALL = 
"/install.php"

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(api_key, secret_key) ⇒ Session

Returns a new instance of Session.



129
130
131
132
 
# File 'lib/facebooker/session.rb', line 129

def initialize(api_key, secret_key)
  @api_key = api_key
  @secret_key = secret_key
end

Instance Attribute Details

#auth_token ⇒ Object 



138
139
140
 
# File 'lib/facebooker/session.rb', line 138

def auth_token
  @auth_token ||= post 'facebook.auth.createToken'
end

#session_key ⇒ Object (readonly)

Returns the value of attribute session_key.



63
64
65
 
# File 'lib/facebooker/session.rb', line 63

def session_key
  @session_key
end

Class Method Details

.api_key ⇒ Object 



72
73
74
 
# File 'lib/facebooker/session.rb', line 72

def self.api_key
  extract_key_from_environment(:api) || extract_key_from_configuration_file(:api) rescue report_inability_to_find_key(:api)
end

.configuration_file_path ⇒ Object 



501
502
503
 
# File 'lib/facebooker/session.rb', line 501

def self.configuration_file_path
  @configuration_file_path || File.expand_path("~/.facebookerrc")
end

.configuration_file_path=(path) ⇒ Object 



505
506
507
 
# File 'lib/facebooker/session.rb', line 505

def self.configuration_file_path=(path)
  @configuration_file_path = path
end

.create(api_key = nil, secret_key = nil) ⇒ Object

Raises:

  • (ArgumentError) 


65
66
67
68
69
70
 
# File 'lib/facebooker/session.rb', line 65

def self.create(api_key=nil, secret_key=nil)
  api_key ||= self.api_key
  secret_key ||= self.secret_key
  raise ArgumentError unless !api_key.nil? && !secret_key.nil?
  new(api_key, secret_key)
end

.current ⇒ Object 



80
81
82
 
# File 'lib/facebooker/session.rb', line 80

def self.current
  Thread.current['facebook_session']
end

.current=(session) ⇒ Object 



84
85
86
 
# File 'lib/facebooker/session.rb', line 84

def self.current=(session)
  Thread.current['facebook_session'] = session
end

.secret_key ⇒ Object 



76
77
78
 
# File 'lib/facebooker/session.rb', line 76

def self.secret_key
  extract_key_from_environment(:secret) || extract_key_from_configuration_file(:secret) rescue report_inability_to_find_key(:secret)
end

Instance Method Details

#add_next_parameters(options) ⇒ Object 



108
109
110
111
112
113
 
# File 'lib/facebooker/session.rb', line 108

def add_next_parameters(options)
  opts = []
  opts << "&next=#{CGI.escape(options[:next])}" if options[:next]
  opts << "&next_cancel=#{CGI.escape(options[:next_cancel])}" if options[:next_cancel]
  opts
end

#add_tags(pid, x, y, tag_uid = nil, tag_text = nil) ⇒ Object 



300
301
302
303
304
305
 
# File 'lib/facebooker/session.rb', line 300

def add_tags(pid, x, y, tag_uid = nil, tag_text = nil )
  if [tag_uid, tag_text].all? {|arg| arg.nil?}
    raise ArgumentError, "Must enter a name or string for this tag"        
  end
  @tags = post('facebook.photos.addTag', :pid => pid, :tag_uid => tag_uid, :tag_text => tag_text, :x => x, :y => y )
end

#add_to_batch(req, &proc) ⇒ Object 



415
416
417
418
419
 
# File 'lib/facebooker/session.rb', line 415

def add_to_batch(req,&proc)
  batch_request = BatchRequest.new(req,proc)
  Thread.current[:facebooker_current_batch_queue]<<batch_request
  batch_request
end

#admin ⇒ Object 



253
254
255
 
# File 'lib/facebooker/session.rb', line 253

def admin
  Facebooker::Admin.new(self)
end

#batch(serial_only = false) ⇒ Object

Submit the enclosed requests for this session inside a batch

All requests will be sent to Facebook at the end of the block each method inside the block will return a proxy object attempting to access the proxy before the end of the block will yield an exception

For Example:

facebook_session.batch do
  @send_result = facebook_session.send_notification([12451752],"Woohoo")
  @albums = facebook_session.user.albums
end
puts @albums.first.inspect

is valid, however

facebook_session.batch do
  @send_result = facebook_session.send_notification([12451752],"Woohoo")
  @albums = facebook_session.user.albums
  puts @albums.first.inspect
end

will raise Facebooker::BatchRequest::UnexecutedRequest

If an exception is raised while processing the result, that exception will be re-raised on the next access to that object or when exception_raised? is called

for example, if the send_notification resulted in TooManyUserCalls being raised, calling 

@send_result.exception_raised?

would re-raise that exception if there was an error retrieving the albums, it would be re-raised when 

@albums.first

is called



456
457
458
459
460
461
462
463
464
465
466
467
 
# File 'lib/facebooker/session.rb', line 456

def batch(serial_only=false)
  @batch_request=true
  Thread.current[:facebooker_current_batch_queue]=[]
  yield
  # Set the batch request to false so that post will execute the batch job
  @batch_request=false
  BatchRun.current_batch=Thread.current[:facebooker_current_batch_queue]
  post("facebook.batch.run",:method_feed=>BatchRun.current_batch.map{|q| q.uri}.to_json,:serial_only=>serial_only.to_s)
ensure
  @batch_request=false
  BatchRun.current_batch=nil
end

#batch_request? ⇒ Boolean

Returns:

  • (Boolean) 


411
412
413
 
# File 'lib/facebooker/session.rb', line 411

def batch_request?
  @batch_request
end

#check_friendship(array_of_pairs_of_users) ⇒ Object

Given an array like:

[userid, otheruserid], [yetanotherid, andanotherid]

returns a Hash indicating friendship of those pairs: otheruserid] => true, [yetanotherid, andanotherid] => false if one of the Hash values is nil, it means the facebook platform’s answer is “I don’t know”



263
264
265
266
267
268
269
270
271
 
# File 'lib/facebooker/session.rb', line 263

def check_friendship(array_of_pairs_of_users)
  uids1 = []
  uids2 = []
  array_of_pairs_of_users.each do |pair|
    uids1 << pair.first
    uids2 << pair.last
  end
  post('facebook.friends.areFriends', :uids1 => uids1.join(','), :uids2 => uids2.join(','))
end

#data ⇒ Object

Returns a proxy object for handling calls to the Facebook Data API



249
250
251
 
# File 'lib/facebooker/session.rb', line 249

def data
  Facebooker::Data.new(self)
end

#default_login_url_options ⇒ Object 



125
126
127
 
# File 'lib/facebooker/session.rb', line 125

def 
  {}
end

#event_members(eid) ⇒ Object 



210
211
212
213
214
215
216
 
# File 'lib/facebooker/session.rb', line 210

def event_members(eid)
  @members ||= post('facebook.events.getMembers', :eid => eid) do |response|
    response.map do |attendee_hash|
      Event::Attendance.from_hash(attendee_hash)
    end
  end
end

#events(options = {}) ⇒ Object

This one has so many parameters, a Hash seemed cleaner than a long param list. Options can be: :uid => Filter by events associated with a user with this uid :eids => Filter by this list of event ids. This is a comma-separated list of eids. :start_time => Filter with this UTC as lower bound. A missing or zero parameter indicates no lower bound. (Time or Integer) :end_time => Filter with this UTC as upper bound. A missing or zero parameter indicates no upper bound. (Time or Integer) :rsvp_status => Filter by this RSVP status.



202
203
204
205
206
207
208
 
# File 'lib/facebooker/session.rb', line 202

def events(options = {})
  @events ||= post('facebook.events.get', options) do |response|
    response.map do |hash|
      Event.from_hash(hash)
    end
  end
end

#expired? ⇒ Boolean

Returns:

  • (Boolean) 


146
147
148
 
# File 'lib/facebooker/session.rb', line 146

def expired?
  @expires.nil? || (!infinite? && Time.at(@expires) <= Time.now)
end

#fields_to_serialize ⇒ Object 



385
386
387
 
# File 'lib/facebooker/session.rb', line 385

def fields_to_serialize
  %w(session_key uid expires secret_from_session auth_token api_key secret_key)
end

#fql_query(query, format = 'XML') ⇒ Object 



166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
 
# File 'lib/facebooker/session.rb', line 166

def fql_query(query, format = 'XML')
  post('facebook.fql.query', :query => query, :format => format) do |response|
    type = response.shift
    if type.nil?
      []
    else
      response.shift.map do |hash|
        case type
        when 'user'
          user = User.new
          user.session = self
          user.populate_from_hash!(hash)
          user
        when 'photo'
          Photo.from_hash(hash)
        when 'event_member'
          Event::Attendance.from_hash(hash)
        else
          hash
        end
      end
    end
  end
end

#get_albums(aids) ⇒ Object 



284
285
286
287
288
289
290
 
# File 'lib/facebooker/session.rb', line 284

def get_albums(aids)
  @albums = post('facebook.photos.getAlbums', :aids => aids) do |response|
    response.map do |hash|        
      Album.from_hash(hash)
    end
  end
end

#get_photos(pids = nil, subj_id = nil, aid = nil) ⇒ Object 



273
274
275
276
277
278
279
280
281
282
 
# File 'lib/facebooker/session.rb', line 273

def get_photos(pids = nil, subj_id = nil,  aid = nil)
  if [subj_id, pids, aid].all? {|arg| arg.nil?}
    raise ArgumentError, "Can't get a photo without a picture, album or subject ID" 
  end
  @photos = post('facebook.photos.get', :subj_id => subj_id, :pids => pids, :aid => aid ) do |response|
    response.map do |hash|
      Photo.from_hash(hash)
    end
  end
end

#get_tags(pids) ⇒ Object 



292
293
294
295
296
297
298
 
# File 'lib/facebooker/session.rb', line 292

def get_tags(pids)
  @tags = post('facebook.photos.getTags', :pids => pids)  do |response|
    response.map do |hash|
      Tag.from_hash(hash)
    end
  end
end

#infinite? ⇒ Boolean

Returns:

  • (Boolean) 


142
143
144
 
# File 'lib/facebooker/session.rb', line 142

def infinite?
  @expires == 0
end

#install_url(options = {}) ⇒ Object 



93
94
95
 
# File 'lib/facebooker/session.rb', line 93

def install_url(options={})
  "#{Facebooker.install_url_base(@api_key)}#{install_url_optional_parameters(options)}"
end

#install_url_optional_parameters(options) ⇒ Object 



102
103
104
105
106
 
# File 'lib/facebooker/session.rb', line 102

def install_url_optional_parameters(options)
  optional_parameters = []      
  optional_parameters += add_next_parameters(options)
  optional_parameters.join
end

#instance_variable_set_value(field, value) ⇒ Object 



377
378
379
 
# File 'lib/facebooker/session.rb', line 377

def instance_variable_set_value(field, value)
  self.instance_variable_set("@#{field}", value)
end

#instance_variable_value(field) ⇒ Object 



381
382
383
 
# File 'lib/facebooker/session.rb', line 381

def instance_variable_value(field)
  self.instance_variable_get("@#{field}")
end

#login_url(options = {}) ⇒ Object 



88
89
90
91
 
# File 'lib/facebooker/session.rb', line 88

def (options={})
  options = .merge(options)
  "#{Facebooker.(@api_key)}#{(options)}"
end

#login_url_optional_parameters(options) ⇒ Object 



115
116
117
118
119
120
121
122
123
 
# File 'lib/facebooker/session.rb', line 115

def (options)
  # It is important that unused options are omitted as stuff like &canvas=false will still display the canvas. 
  optional_parameters = []
  optional_parameters += add_next_parameters(options)
  optional_parameters << "&skipcookie=true" if options[:skip_cookie]
  optional_parameters << "&hide_checkbox=true" if options[:hide_checkbox]
  optional_parameters << "&canvas=true" if options[:canvas]
  optional_parameters.join
end

#marshal_dump ⇒ Object

Only serialize the bare minimum to recreate the session.



362
363
364
 
# File 'lib/facebooker/session.rb', line 362

def marshal_dump#:nodoc:
  fields_to_serialize.map{|field| instance_variable_value(field)}
end

#marshal_load(variables) ⇒ Object

Only serialize the bare minimum to recreate the session.



357
358
359
 
# File 'lib/facebooker/session.rb', line 357

def marshal_load(variables)#:nodoc:
  fields_to_serialize.each_with_index{|field, index| instance_variable_set_value(field, variables[index])}
end

#pages(options = {}) ⇒ Object

Raises:

  • (ArgumentError) 


230
231
232
233
234
235
236
237
238
 
# File 'lib/facebooker/session.rb', line 230

def pages(options = {})
  raise ArgumentError, 'fields option is mandatory' unless options.has_key?(:fields)
  @pages ||= {}
  @pages[options] ||= post('facebook.pages.getInfo', options) do |response|
    response.map do |hash|
      Page.from_hash(hash)
    end
  end
end

#permission_url(permission, options = {}) ⇒ Object 



97
98
99
100
 
# File 'lib/facebooker/session.rb', line 97

def permission_url(permission,options={})
  options = .merge(options)
  "http://#{Facebooker.www_server_base_url}/authorize.php?api_key=#{@api_key}&v=1.0&ext_perm=#{permission}#{install_url_optional_parameters(options)}"
end

#post(method, params = {}, use_session_key = true, &proc) ⇒ Object 



482
483
484
485
486
487
488
489
490
 
# File 'lib/facebooker/session.rb', line 482

def post(method, params = {}, use_session_key = true, &proc)
  if batch_request?
    post_without_logging(method, params, use_session_key, &proc)
  else
    Logging.log_fb_api(method, params) do
      post_without_logging(method, params, use_session_key, &proc)
    end
  end
end

#post_file(method, params = {}) ⇒ Object 



492
493
494
495
496
497
498
 
# File 'lib/facebooker/session.rb', line 492

def post_file(method, params = {})
  Logging.log_fb_api(method, params) do
    add_facebook_params(params, method)
    @session_key && params[:session_key] ||= @session_key
    service.post_file(params.merge(:sig => signature_for(params.reject{|key, value| key.nil?})))
  end
end

#post_without_logging(method, params = {}, use_session_key = true, &proc) ⇒ Object 



469
470
471
472
473
474
475
476
477
478
479
480
 
# File 'lib/facebooker/session.rb', line 469

def post_without_logging(method, params = {}, use_session_key = true, &proc)
  add_facebook_params(params, method)
  use_session_key && @session_key && params[:session_key] ||= @session_key
  final_params=params.merge(:sig => signature_for(params))
  if batch_request?
    add_to_batch(final_params,&proc)
  else
    result = service.post(final_params)
    result = yield result if block_given?
    result
  end
end

#publish_user_action(bundle_id, data = {}, target_ids = nil, body_general = nil) ⇒ Object

publish a previously rendered template bundle see wiki.developers.facebook.com/index.php/Feed.publishUserAction



340
341
342
343
344
345
 
# File 'lib/facebooker/session.rb', line 340

def publish_user_action(bundle_id,data={},target_ids=nil,body_general=nil)
  parameters={:template_bundle_id=>bundle_id,:template_data=>data.to_json}
  parameters[:target_ids] = target_ids unless target_ids.blank?
  parameters[:body_general] = body_general unless body_general.blank?
  post("facebook.feed.publishUserAction", parameters)
end

#register_template_bundle(one_line_story_templates, short_story_templates = nil, full_story_template = nil, action_links = nil) ⇒ Object

Register a template bundle with Facebook. returns the template id to use to send using this template



324
325
326
327
328
329
330
331
332
333
334
 
# File 'lib/facebooker/session.rb', line 324

def register_template_bundle(one_line_story_templates,short_story_templates=nil,full_story_template=nil, action_links=nil)
  parameters = {:one_line_story_templates => Array(one_line_story_templates).to_json}
  
  parameters[:action_links] = action_links.to_json unless action_links.blank?
  
  parameters[:short_story_templates] = Array(short_story_templates).to_json unless short_story_templates.blank?

  parameters[:full_story_template] = full_story_template.to_json unless full_story_template.blank?

  post("facebook.feed.registerTemplateBundle", parameters, false)
end

#secret_for_method(method_name) ⇒ Object 



134
135
136
 
# File 'lib/facebooker/session.rb', line 134

def secret_for_method(method_name)
  @secret_key
end

#secure! ⇒ Object 



154
155
156
157
 
# File 'lib/facebooker/session.rb', line 154

def secure!
  response = post 'facebook.auth.getSession', :auth_token => auth_token
  secure_with!(response['session_key'], response['uid'], response['expires'], response['secret'])
end

#secure_with!(session_key, uid = nil, expires = nil, secret_from_session = nil) ⇒ Object 



159
160
161
162
163
164
 
# File 'lib/facebooker/session.rb', line 159

def secure_with!(session_key, uid = nil, expires = nil, secret_from_session = nil)
  @session_key = session_key
  @uid = uid ? Integer(uid) : post('facebook.users.getLoggedInUser', :session_key => session_key)
  @expires = Integer(expires)
  @secret_from_session = secret_from_session
end

#secured? ⇒ Boolean

Returns:

  • (Boolean) 


150
151
152
 
# File 'lib/facebooker/session.rb', line 150

def secured?
  !@session_key.nil? && !expired?
end

#send_email(user_ids, subject, text, fbml = nil) ⇒ Object

Send email to as many as 100 users at a time



350
351
352
353
354
 
# File 'lib/facebooker/session.rb', line 350

def send_email(user_ids, subject, text, fbml = nil) 			
  user_ids = Array(user_ids)
  params = {:fbml => fbml, :recipients => user_ids.map{ |id| User.cast_to_facebook_id(id)}.join(','), :text => text, :subject => subject} 
  post 'facebook.notifications.sendEmail', params
end

#send_notification(user_ids, fbml, email_fbml = nil) ⇒ Object 



307
308
309
310
311
312
313
314
315
316
317
318
319
 
# File 'lib/facebooker/session.rb', line 307

def send_notification(user_ids, fbml, email_fbml = nil)
  params = {:notification => fbml, :to_ids => user_ids.map{ |id| User.cast_to_facebook_id(id)}.join(',')}
  if email_fbml
    params[:email] = email_fbml
  end
  params[:type]="user_to_user"
  # if there is no uid, this is an announcement
  unless uid?
    params[:type]="app_to_user"
  end
  
  post 'facebook.notifications.send', params,uid?
end

#server_cache ⇒ Object

Returns a proxy object for handling calls to Facebook cached items such as images and FBML ref handles



243
244
245
 
# File 'lib/facebooker/session.rb', line 243

def server_cache
  Facebooker::ServerCache.new(self)
end

#to_yaml(opts = {}) ⇒ Object

Only serialize the bare minimum to recreate the session.



367
368
369
370
371
372
373
374
375
 
# File 'lib/facebooker/session.rb', line 367

def to_yaml( opts = {} )
  YAML::quick_emit(self.object_id, opts) do |out|
    out.map(taguri) do |map|
      fields_to_serialize.each do |field|
        map.add(field, instance_variable_value(field))
      end
    end
  end
end

#user ⇒ Object 



191
192
193
 
# File 'lib/facebooker/session.rb', line 191

def user
  @user ||= User.new(uid, self)
end

#users(user_ids, fields = []) ⇒ Object 



224
225
226
227
228
 
# File 'lib/facebooker/session.rb', line 224

def users(user_ids, fields=[])
  post("facebook.users.getInfo",:uids=>user_ids.join(","),:fields=>User.user_fields(fields)) do |users|
    users.map { |u| User.new(u)}
  end
end

#users_standard(user_ids, fields = []) ⇒ Object 



218
219
220
221
222
 
# File 'lib/facebooker/session.rb', line 218

def users_standard(user_ids, fields=[])
  post("facebook.users.getStandardInfo",:uids=>user_ids.join(","),:fields=>User.standard_fields(fields)) do |users|
    users.map { |u| User.new(u)}
  end
end