Class: Viddler::Base

Inherits:
Object
  • Object
show all
Defined in:
lib/viddler/base.rb

Overview

A class that can be instantiated for access to a Viddler API.

Examples:

@viddler = Viddler::Base.new(API_KEY, USERNAME, PASSWORD)

Username and password are optional, some API methods doesn’t require them:

@viddler = Viddler::Base.new(YOUR_API_KEY)

Instance Method Summary collapse

Constructor Details

#initialize(api_key, username = nil, password = nil) ⇒ Base

Creates new viddler instance.

Example:

@viddler = Viddler::Base.new(api_key, username, password)



38
39
40
41
 
# File 'lib/viddler/base.rb', line 38

def initialize(api_key, username=nil, password=nil)
  @api_key, @username, @password = api_key, username, password
  @session_id = nil
end

Instance Method Details

#authenticate ⇒ Object

Implements viddler.users.auth[http://wiki.developers.viddler.com/index.php/Viddler.users.auth].

It’s not necessary for you to call this method manually before each method that requires authentication. Viddler.rb will do that for you automatically. You can use this method for checking credentials and for trying if connection to Viddler works.

Example:

@viddler.authenticate

Returns a string with session id.

Raises:



53
54
55
56
57
58
59
60
61
62
 
# File 'lib/viddler/base.rb', line 53

def authenticate
  raise AuthenticationRequiredError unless could_authenticate?
  request = Viddler::Request.new(:get, 'users.auth')
  request.run do |p|
    p.api_key     = @api_key
    p.user        = @username
    p.password    = @password
  end
  @session_id = request.response['auth']['sessionid']
end

#authenticated? ⇒ Boolean

Returns:

  • (Boolean) 


64
65
66
 
# File 'lib/viddler/base.rb', line 64

def authenticated?
  @session_id ? true : false
end

#delete_comment(id) ⇒ Object 



436
437
438
439
440
441
442
443
444
 
# File 'lib/viddler/base.rb', line 436

def delete_comment(id)
  authenticate unless authenticated?
  request = Viddler::Request.new(:post, 'videos.comments.remove')
  request.run do |p|
    p.api_key     = @api_key
    p.sessionid   = @session_id 
    p.comment_id  = id
  end
end

#delete_video(id) ⇒ Object 



426
427
428
429
430
431
432
433
434
 
# File 'lib/viddler/base.rb', line 426

def delete_video(id)
  authenticate unless authenticated?
  request = Viddler::Request.new(:post, 'videos.delete')
  request.run do |p|
    p.api_key     = @api_key
    p.sessionid   = @session_id 
    p.video_id  = id
  end
end

#find_all_featured_videos ⇒ Object

Implements viddler.videos.getFeatured[http://wiki.developers.viddler.com/index.php/Viddler.videos.getFeatured].

Example:

@viddler.find_all_featured_videos

Returns array of Viddler::Video instances.



418
419
420
421
422
423
424
 
# File 'lib/viddler/base.rb', line 418

def find_all_featured_videos    
  request = Viddler::Request.new(:get, 'videos.getFeatured')
  request.run do |p|
    p.api_key     = @api_key
  end
  parse_videos_list(request.response['video_list'])
end

#find_all_videos_by_tag(tag_name, options = {}) ⇒ Object

Implements viddler.videos.getByTag[http://wiki.developers.viddler.com/index.php/Viddler.videos.getByTag].

Options hash could contain next values:

  • page: The “page number” of results to retrieve (e.g. 1, 2, 3);

  • per_page: The number of results to retrieve per page (maximum 100). If not specified, the default value equals 20.

Example:

@viddler.find_all_videos_by_tag('super tag', :per_page => 5)

Returns array of Viddler::Video instances.



397
398
399
400
401
402
403
404
405
406
407
408
 
# File 'lib/viddler/base.rb', line 397

def find_all_videos_by_tag(tag_name, options={})
  options.assert_valid_keys(:page, :per_page)

  request = Viddler::Request.new(:get, 'videos.getByTag')
  request.run do |p|
    p.api_key     = @api_key
    p.tag         = tag_name
    p.page        = options[:page] || 1
    p.per_page    = options[:per_page] || 20
  end
  parse_videos_list(request.response['video_list'])
end

#find_all_videos_by_user(username, options = {}) ⇒ Object

Implements viddler.videos.getByUser[http://wiki.developers.viddler.com/index.php/Viddler.videos.getByUser]. Authentication is optional.

Options hash could contain next values:

  • page: The “page number” of results to retrieve (e.g. 1, 2, 3);

  • per_page: The number of results to retrieve per page (maximum 100). If not specified, the default value equals 20.

Example:

@viddler.find_all_videos_by_user(username, :page => 2)

Returns array of Viddler::Video instances.



369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
 
# File 'lib/viddler/base.rb', line 369

def find_all_videos_by_user(username, options={})
  authenticate if could_authenticate? and !authenticated?

  options.assert_valid_keys(:page, :per_page)

  request = Viddler::Request.new(:get, 'videos.getByUser')
  request.run do |p|
    p.api_key     = @api_key
    p.sessionid   = @session_id if authenticated?
    p.user        = username
    p.page        = options[:page] || 1
    p.per_page    = options[:per_page] || 20      
  end
  parse_videos_list(request.response['video_list'])    
end

#find_profile(viddler_name) ⇒ Object

Implements viddler.users.getProfile[http://wiki.developers.viddler.com/index.php/Viddler.users.getProfile].

Example:

@viddler.find_profile(viddler_username)

Returns Viddler::User instance.



170
171
172
173
174
175
176
177
 
# File 'lib/viddler/base.rb', line 170

def find_profile(viddler_name)
  request = Viddler::Request.new(:get, 'users.getProfile')
  request.run do |p|
    p.api_key     = @api_key
    p.user        = viddler_name
  end
  Viddler::User.new request.response['user']
end

#find_video_by_id(video_id) ⇒ Object

Implements viddler.videos.getDetails[http://wiki.developers.viddler.com/index.php/Viddler.videos.getDetails]. Authentication is optional.

Example:

@viddler.find_video_by_id(video_id)

Returns Viddler::Video instance.



271
272
273
274
275
276
277
278
279
280
281
282
 
# File 'lib/viddler/base.rb', line 271

def find_video_by_id(video_id)
  # Authentication is optional for this request
  authenticate if could_authenticate? and !authenticated?

  request = Viddler::Request.new(:get, 'videos.getDetails')
  request.run do |p|
    p.api_key     = @api_key
    p.video_id    = video_id
    p.sessionid   = @session_id if authenticated?
  end
  Viddler::Video.new(request.response['video'])
end

#find_video_by_url(video_url) ⇒ Object

Implements viddler.videos.getDetailsByUrl[http://wiki.developers.viddler.com/index.php/Viddler.videos.getDetailsByUrl]. Authentication is optional.

Example:

@viddler.find_video_by_url('http://www.viddler.com/explore/username/videos/video_num/')

Returns Viddler::Video instance.



292
293
294
295
296
297
298
299
300
301
302
303
 
# File 'lib/viddler/base.rb', line 292

def find_video_by_url(video_url)
  # Authentication is optional for this request
  authenticate if could_authenticate? and !authenticated?

  request = Viddler::Request.new(:get, 'videos.getDetailsByUrl')
  request.run do |p|
    p.sessionid   = @session_id if authenticated?
    p.api_key     = @api_key
    p.url         = video_url      
  end
  Viddler::Video.new(request.response['video'])
end

#get_record_token ⇒ Object

Implements viddler.videos.getRecordToken[http://wiki.developers.viddler.com/index.php/Viddler.videos.getRecordToken].

Example:

@viddler.get_record_token

Returns a string with record token.



76
77
78
79
80
81
82
83
84
85
 
# File 'lib/viddler/base.rb', line 76

def get_record_token
  authenticate unless authenticated?
  
  request = Viddler::Request.new(:get, 'videos.getRecordToken')
  request.run do |p|
    p.api_key     = @api_key
    p.sessionid   = @session_id
  end
  request.response['record_token']
end

#get_video_status(video_id) ⇒ Object

Implements viddler.videos.getStatus[http://wiki.developers.viddler.com/index.php/Viddler.vidoes.getStatus].

Example:

@viddler.get_video_status(video_id)

This methods returns OpenStruct instance with Viddler’s status information on a given video. We don’t control what Viddler returns and it’s all basically technical internal information of Viddler. Use this on your own risk.



254
255
256
257
258
259
260
261
 
# File 'lib/viddler/base.rb', line 254

def get_video_status(video_id)
  request = Viddler::Request.new(:get, 'videos.getStatus')
  request.run do |p|
    p.api_key     = @api_key
    p.video_id    = video_id
  end
  OpenStruct.new request.response['video_status']      
end

#register_user(new_attributes = {}) ⇒ Object

Implements viddler.users.register[http://wiki.developers.viddler.com/index.php/Viddler.users.register]. Restricted to Viddler qualified API keys only.

new_attributes hash should contain next required keys:

  • user: The chosen Viddler user name;

  • email: The email address of the user;

  • fname: The user’s first name;

  • lname: The user’s last name;

  • password: The user’s password with Viddler;

  • question: The text of the user’s secret question;

  • answer: The text of the answer to the secret question;

  • lang: The language of the user for the account (e.g. EN)

  • termsaccepted: “1” indicates the user has accepted Viddler’s terms and conditions.

and could contain next optional keys:

  • company: The user’s company affiliation.

Example:

@viddler.register_user(:user => 'login', :email => '[email protected]', ...)

Returns new user’s username string.



109
110
111
112
113
114
115
116
117
118
119
120
 
# File 'lib/viddler/base.rb', line 109

def register_user(new_attributes={})
  Viddler::ApiSpec.check_attributes('users.register', new_attributes)
  
  request = Viddler::Request.new(:get, 'users.register')
  request.run do |p|
    p.api_key     = @api_key
    for param, value in new_attributes
      p.send("#{param}=", value)
    end
  end
  request.response['user']['username']
end

#set_permalink(video_id, url) ⇒ Object 



345
346
347
348
349
350
351
352
353
354
355
 
# File 'lib/viddler/base.rb', line 345

def set_permalink(video_id, url)
  authenticate unless authenticated?
  
  request = Viddler::Request.new(:post, 'videos.setPermalink')
  request.run do |p|
    p.api_key   = @api_key
    p.sessionid = @session_id
    p.video_id  = video_id
    p.permalink  = url
  end
end

#update_account(new_attributes = {}) ⇒ Object

Implements viddler.users.setOptions[http://wiki.developers.viddler.com/index.php/Viddler.users.setOptions]. Requires authentication. Restricted to Viddler partners only.

new_attributes hash could contain next optional keys:

  • show_account: “1”, “0” - Show/hide your account in Viddler. If you set it to “0” both your account and your videos won’t be visible on viddler.com site

  • tagging_enabled: “1”, “0” - Enable/disable tagging on all your videos

  • commenting_enabled: “1”, “0” - Enable/disable commenting on all your videos

  • show_related_videos: “1”, “0” - Show/hide related videos on all your videos

  • embedding_enabled: “1”, “0” - Enable/disable embedding of off all your videos

  • clicking_through_enabled: “1”, “0” - Enable/disable redirect to viddler site while clicking on embedded player

  • email_this_enabled: “1”, “0” - Enable/disable email this option on all your videos

  • trackbacks_enabled: “1”, “0” - Enable/disable trackbacks on all your videos

  • favourites_enabled: “1”, “0” - Enable/disable favourites on all your videos

  • custom_logo_enabled: “1”, “0” - Enable/disable custom logo on all your videos. Note that logo itself must be send to viddler manually.

Example:

@viddler.(:show_account => '0')

Returns number of updated parameters.



231
232
233
234
235
236
237
238
239
240
241
242
243
244
 
# File 'lib/viddler/base.rb', line 231

def (new_attributes={})
  authenticate unless authenticated?
  Viddler::ApiSpec.check_attributes('users.setOptions', new_attributes)
  
  request = Viddler::Request.new(:get, 'users.setOptions')
  request.run do |p|
    p.api_key   = @api_key
    p.sessionid = @session_id
    for param, value in new_attributes
      p.send("#{param}=", value)
    end
  end
  request.response['updated'].to_i
end

#update_profile(new_attributes = {}) ⇒ Object

Implements viddler.users.setProfile[http://wiki.developers.viddler.com/index.php/Viddler.users.setProfile]. Requires authentication.

new_attributes hash could contain next optional keys:

  • first_name

  • last_name

  • about_me

  • birthdate: Birthdate in yyyy-mm-dd format;

  • gender: Either m or y.

  • company

  • city

Example:

@viddler.update_profile(:first_name => 'Vasya', :last_name => 'Pupkin')

Returns Viddler::User instance.



196
197
198
199
200
201
202
203
204
205
206
207
208
209
 
# File 'lib/viddler/base.rb', line 196

def update_profile(new_attributes={})
  authenticate unless authenticated?
  Viddler::ApiSpec.check_attributes('users.setProfile', new_attributes)
  
  request = Viddler::Request.new(:post, 'users.setProfile')
  request.run do |p|
    p.api_key   = @api_key
    p.sessionid = @session_id
    for param, value in new_attributes
      p.send("#{param}=", value)
    end
  end
  Viddler::User.new request.response['user']
end

#update_video(video_id, new_attributes = {}) ⇒ Object

Implements viddler.videos.setDetails[http://wiki.developers.viddler.com/index.php/Viddler.videos.setDetails]. Requires authentication.

new_attributes hash could contain next optional keys:

  • title: Video title - 500 characters max

  • description: Video description

  • tags: List of tags to be set on video. Setting tags will update current tags set (both timed and global video tags). To set timed tag use format tagname as tagname. For example - using tag1,tag2,tag3 will set 2 global and 1 timed tag at 2.5s

  • view_perm: View permission. Can be set to public, shared_all, shared or private

  • view_users: List of users which may view this video if view_perm is set to shared. Only your viddler friends are allowed here. If you provide multiple usernames - non valid viddler friends usernames will be ignored.

  • view_use_secret: If view_perm is set to non public value, you may activate secreturl for your video. If you want to enable or regenerate secreturl pass “1” as parameter value. If you want to disable secreturl pass “0” as parameter value.

  • embed_perm: Embedding permission. Supported permission levels are the same as for view_perm. This and all permissions below cannot be less restrictive than view_perm. You cannot set it to public if view_perm is for example shared.

  • embed_users: Same as view_users. If view_perm is shared, this list cannot contain more users than view_users. Invalid usernames will be removed.

  • commenting_perm: Commenting permission. Description is the same as for embed_perm

  • commenting_users: Same as embed_users.

  • tagging_perm: Tagging permission. Description is the same as for embed_perm

  • tagging_users: Same as embed_users.

  • download_perm: Download permission. Description is the same as for embed_perm

  • download_users: Same as embed_users.

Example:

@viddler.update_video(video_id, :title => 'Brand new title')

Returns Viddler::Video instance.



329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
 
# File 'lib/viddler/base.rb', line 329

def update_video(video_id, new_attributes={})
  authenticate unless authenticated?
  Viddler::ApiSpec.check_attributes('videos.setDetails', new_attributes)
  
  request = Viddler::Request.new(:get, 'videos.setDetails')
  request.run do |p|
    p.api_key   = @api_key
    p.sessionid = @session_id
    p.video_id  = video_id
    for param, value in new_attributes
      p.send("#{param}=", value)
    end
  end
  Viddler::Video.new(request.response['video'])
end

#upload_video(new_attributes = {}) ⇒ Object

Implements viddler.videos.upload[http://wiki.developers.viddler.com/index.php/Viddler.videos.upload]. Requires authentication.

new_attributes hash should contain next required keys:

  • title: The video title;

  • description: The video description;

  • tags: The video tags;

  • file: The video file;

  • make_public: Use “1” for true and “0” for false to choose whether or not the video goes public when uploaded.

Example:

@viddler.upload_video(:title => 'Great Title', :file => File.open('/movies/movie.mov'), ...)

Returns Viddler::Video instance.



137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
 
# File 'lib/viddler/base.rb', line 137

def upload_video(new_attributes={})
  authenticate unless authenticated?
  Viddler::ApiSpec.check_attributes('videos.upload', new_attributes)

  # Get an upload endpoint
  request = Viddler::Request.new(:post, 'viddler.videos.prepareUpload')
  request.run do |p|
    p.api_key     = @api_key
    p.sessionid   = @session_id
  end
  endpoint = request.response['upload']['endpoint'] 

  # Upload to endpoint url
  request = Viddler::Request.new(:post, 'videos.upload')
  request.url = endpoint
  request.run do |p|
    p.api_key     = @api_key
    p.sessionid   = @session_id
    for param, value in new_attributes
      p.send("#{param}=", value)
    end
  end
  Viddler::Video.new(request.response['video'])
end