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 Attribute Summary collapse

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)



40
41
42
43
 
# File 'lib/viddler/base.rb', line 40

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

Instance Attribute Details

#password ⇒ Object

Returns the value of attribute password.



32
33
34
 
# File 'lib/viddler/base.rb', line 32

def password
  @password
end

#session_id ⇒ Object

Returns the value of attribute session_id.



32
33
34
 
# File 'lib/viddler/base.rb', line 32

def session_id
  @session_id
end

#username ⇒ Object

Returns the value of attribute username.



32
33
34
 
# File 'lib/viddler/base.rb', line 32

def username
  @username
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:



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

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) 


66
67
68
 
# File 'lib/viddler/base.rb', line 66

def authenticated?
  @session_id ? true : false
end

#delete_comment(id) ⇒ Object 



447
448
449
450
451
452
453
454
455
 
# File 'lib/viddler/base.rb', line 447

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(video_id) ⇒ Object

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

Example:

@viddler.delete_video(video_id)

Returns true for success or false for failure



132
133
134
135
136
137
138
139
140
141
 
# File 'lib/viddler/base.rb', line 132

def delete_video(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  = video_id
  end
  request.response.key? 'success'
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.



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

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.



418
419
420
421
422
423
424
425
426
427
428
429
 
# File 'lib/viddler/base.rb', line 418

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.



390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
 
# File 'lib/viddler/base.rb', line 390

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
    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.



151
152
153
154
155
156
157
158
 
# File 'lib/viddler/base.rb', line 151

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.



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

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.



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

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.



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

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.



235
236
237
238
239
240
241
242
 
# File 'lib/viddler/base.rb', line 235

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.



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

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 



326
327
328
329
330
331
332
333
334
335
336
 
# File 'lib/viddler/base.rb', line 326

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.



212
213
214
215
216
217
218
219
220
221
222
223
224
225
 
# File 'lib/viddler/base.rb', line 212

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.



177
178
179
180
181
182
183
184
185
186
187
188
189
190
 
# File 'lib/viddler/base.rb', line 177

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.



310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
 
# File 'lib/viddler/base.rb', line 310

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 all 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.



353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
 
# File 'lib/viddler/base.rb', line 353

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