Class: Facebooker::Session

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

Direct Known Subclasses

CanvasSession, MockSession, 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.



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

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

Instance Attribute Details

#auth_token ⇒ Object 



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

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 



525
526
527
 
# File 'lib/facebooker/session.rb', line 525

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

.configuration_file_path=(path) ⇒ Object 



529
530
531
 
# File 'lib/facebooker/session.rb', line 529

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 



121
122
123
124
125
126
 
# File 'lib/facebooker/session.rb', line 121

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 



323
324
325
326
327
328
 
# File 'lib/facebooker/session.rb', line 323

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 



438
439
440
441
442
 
# File 'lib/facebooker/session.rb', line 438

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 



272
273
274
 
# File 'lib/facebooker/session.rb', line 272

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



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

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) 


434
435
436
 
# File 'lib/facebooker/session.rb', line 434

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”



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

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



268
269
270
 
# File 'lib/facebooker/session.rb', line 268

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

#default_login_url_options ⇒ Object 



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

def 
  {}
end

#event_members(eid) ⇒ Object 



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

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.



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

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) 


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

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

#fields_to_serialize ⇒ Object 



408
409
410
 
# File 'lib/facebooker/session.rb', line 408

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 



179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
 
# File 'lib/facebooker/session.rb', line 179

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 'page'
        Page.from_hash(hash)
      when 'page_admin'
        Page.from_hash(hash)
      when 'event_member'
        Event::Attendance.from_hash(hash)
      else
        hash
      end
    end
  end
end

#get_albums(aids) ⇒ Object 



307
308
309
310
311
312
313
 
# File 'lib/facebooker/session.rb', line 307

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 



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

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 



315
316
317
318
319
320
321
 
# File 'lib/facebooker/session.rb', line 315

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) 


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

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 



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

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 



400
401
402
 
# File 'lib/facebooker/session.rb', line 400

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

#instance_variable_value(field) ⇒ Object 



404
405
406
 
# File 'lib/facebooker/session.rb', line 404

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

#is_fan(page_id, uid) ⇒ Object

Takes page_id and uid, returns true if uid is a fan of the page_id



255
256
257
 
# File 'lib/facebooker/session.rb', line 255

def is_fan(page_id, uid)
  post('facebook.pages.isFan', :page_id=>page_id, :uid=>uid)
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 



128
129
130
131
132
133
134
135
136
 
# File 'lib/facebooker/session.rb', line 128

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.



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

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.



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

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

#mobile ⇒ Object 



276
277
278
 
# File 'lib/facebooker/session.rb', line 276

def mobile
  Facebooker::Mobile.new(self)
end

#pages(options = {}) ⇒ Object

Raises:

  • (ArgumentError) 


244
245
246
247
248
249
250
251
252
 
# File 'lib/facebooker/session.rb', line 244

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

The url to get user to approve extended permissions wiki.developers.facebook.com/index.php/Extended_permission

permissions:

  • email

  • offline_access

  • status_update

  • photo_upload

  • video_upload

  • create_listing

  • create_event

  • rsvp_event

  • sms



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

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 



505
506
507
508
509
510
511
512
513
 
# File 'lib/facebooker/session.rb', line 505

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 



515
516
517
518
519
520
521
522
 
# File 'lib/facebooker/session.rb', line 515

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

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



492
493
494
495
496
497
498
499
500
501
502
503
 
# File 'lib/facebooker/session.rb', line 492

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



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

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



347
348
349
350
351
352
353
354
355
356
357
 
# File 'lib/facebooker/session.rb', line 347

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 



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

def secret_for_method(method_name)
  @secret_key
end

#secure! ⇒ Object 



167
168
169
170
 
# File 'lib/facebooker/session.rb', line 167

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 



172
173
174
175
176
177
 
# File 'lib/facebooker/session.rb', line 172

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) 


163
164
165
 
# File 'lib/facebooker/session.rb', line 163

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



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

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 



330
331
332
333
334
335
336
337
338
339
340
341
342
 
# File 'lib/facebooker/session.rb', line 330

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



262
263
264
 
# File 'lib/facebooker/session.rb', line 262

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

#to_yaml(opts = {}) ⇒ Object

Only serialize the bare minimum to recreate the session.



390
391
392
393
394
395
396
397
398
 
# File 'lib/facebooker/session.rb', line 390

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 



205
206
207
 
# File 'lib/facebooker/session.rb', line 205

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

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



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

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 



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

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