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 



507
508
509
 
# File 'lib/facebooker/session.rb', line 507

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

.configuration_file_path=(path) ⇒ Object 



511
512
513
 
# File 'lib/facebooker/session.rb', line 511

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
  @current_session
end

.current=(session) ⇒ Object 



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

def self.current=(session)
  @current_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 



297
298
299
300
301
302
 
# File 'lib/facebooker/session.rb', line 297

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 



421
422
423
424
425
 
# File 'lib/facebooker/session.rb', line 421

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 



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

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



462
463
464
465
466
467
468
469
470
471
472
473
 
# File 'lib/facebooker/session.rb', line 462

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) 


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

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”



260
261
262
263
264
265
266
267
268
 
# File 'lib/facebooker/session.rb', line 260

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



246
247
248
 
# File 'lib/facebooker/session.rb', line 246

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 



207
208
209
210
211
212
213
 
# File 'lib/facebooker/session.rb', line 207

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.



199
200
201
202
203
204
205
 
# File 'lib/facebooker/session.rb', line 199

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 



391
392
393
 
# File 'lib/facebooker/session.rb', line 391

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
 
# 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
    return [] if type.nil?
    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

#get_albums(aids) ⇒ Object 



281
282
283
284
285
286
287
 
# File 'lib/facebooker/session.rb', line 281

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 



270
271
272
273
274
275
276
277
278
279
 
# File 'lib/facebooker/session.rb', line 270

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 



289
290
291
292
293
294
295
 
# File 'lib/facebooker/session.rb', line 289

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 



383
384
385
 
# File 'lib/facebooker/session.rb', line 383

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

#instance_variable_value(field) ⇒ Object 



387
388
389
 
# File 'lib/facebooker/session.rb', line 387

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.



368
369
370
 
# File 'lib/facebooker/session.rb', line 368

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.



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

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) 


227
228
229
230
231
232
233
234
235
 
# File 'lib/facebooker/session.rb', line 227

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 



488
489
490
491
492
493
494
495
496
 
# File 'lib/facebooker/session.rb', line 488

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 



498
499
500
501
502
503
504
 
# File 'lib/facebooker/session.rb', line 498

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 



475
476
477
478
479
480
481
482
483
484
485
486
 
# File 'lib/facebooker/session.rb', line 475

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



346
347
348
349
350
351
 
# File 'lib/facebooker/session.rb', line 346

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



321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
 
# File 'lib/facebooker/session.rb', line 321

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

  if !full_story_template.blank?
    parameters[:full_story_template]= full_story_template.to_json
  end
  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



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

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 



304
305
306
307
308
309
310
311
312
313
314
315
316
 
# File 'lib/facebooker/session.rb', line 304

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



240
241
242
 
# File 'lib/facebooker/session.rb', line 240

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

#to_yaml(opts = {}) ⇒ Object

Only serialize the bare minimum to recreate the session.



373
374
375
376
377
378
379
380
381
 
# File 'lib/facebooker/session.rb', line 373

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 



188
189
190
 
# File 'lib/facebooker/session.rb', line 188

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

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



221
222
223
224
225
 
# File 'lib/facebooker/session.rb', line 221

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 



215
216
217
218
219
 
# File 'lib/facebooker/session.rb', line 215

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