NAME

Net::VKontakte::Standalone - Perl extension for creating standalone Vkontakte API applications

SYNOPSIS

  use Net::VKontakte::Standalone;
  my $vk = new Net::VKontakte::Standalone:: "12345678";
  my $auth_uri = $vk->auth_uri("wall,messages");

  # make the user able to enter login and password at this URI
  
  $vk->redirected($where);
  $vk->api("activity.set",{text => "playing with VK API"});

DESCRIPTION

This module is just a wrapper for some JSON parsing and WWW::Mechanize magic, not much else.

CONSTRUCTOR METHODS

$vk = Net::VKontakte::Standalone::->new($api_id);

$vk = Net::Vkontalte::Standalone::->new( key => value );

This creates the main object, sets the API ID variable (which can be got from the application management page) and creates the WWW::Mechanize object.

Possible keys:

api_id

API ID of the application, required unless access_token is specified.

access_token

A valid access_token (for example, a permament token got from persistent storage). Required unless api_id is specified.

errors_noauto

If true, return undef instead of automatic error handling (which includes limiting requests per second and throwing exceptions). If this is a coderef, it will be called with the {error} subhash as the only argument. In both cases the error will be stored and will be accessible via $vk->error method.

captcha_handler

Should be a coderef to be called upon receiving {error} requiring CAPTCHA. The coderef will be called with the CAPTCHA URL as the only argument and should return the captcha answer (decoded to characters if needed). Works even when errors_noauto is true (or a coderef).

METHODS

$vk->auth($login,$password,$scope)

This method should be called first. It uses OAuth2 to authentificate the user at the vk.com server and accepts the specified scope (seen at http://vk.com/dev/permissions). After obtaining the access token is saved for future use.

This is not a recommended way to authentificate standalone VKontakte applications, but it works (for now). Feel free to use it in small hacks but stay away from it in production.

$vk->auth_uri($scope)

This method should be called first. It returns the URI of the login page to show to the user (developer should call a browser somehow, see http://vk.com/dev/auth_mobile for more info).

The $scope parameter is described at http://vk.com/dev/permissions.

$vk->redirected($uri)

This method should be called after a successful authorisation with the URI user was redirected to. Then the expiration time and the access token are retreived from this URI and stored in the $vk object.

$vk->permament_token(params => "values", ...);

This method provides another way of (non-interactive) authentification:

Your application should be trusted by VK.com

The token is permament, it can be stored and used again

You should not store the login and the password

Required parameters are:

client_secret

Your application's secret

username

User's login

password

User's password

Optional parameters are:

scope

Needed access rights, as in http://vk.com/dev/permissions

test_redirect_uri

Set it to 1 to initiate test check of the user using redirect_uri error. Set 0 otherwise (by default).

Read more about permament tokens at http://vk.com/dev/auth_direct.

This method respects captcha_handler and errors_noauto parameters of the $vk object.

$vk->api($method,{parameter => "value", parameter => "value" ...})

This method calls the API methods on the server, as described on http://vk.com/dev/api_requests. Resulting JSON is parsed and returned as a hash reference.

$vk->post($url, parameter => "value", file_parameter => [$filename, ...], ... )

This method makes uploading files (see http://vk.com/dev/upload_files) a lot easier.

Firstly, get the upload URI using the respective API method. Secondly, use this method to upload the file (NOTE: no return value error checking is done because return values are not consistent between different uploads). Finally, pass the gathered data structure to the another API method which completes your upload.

HTTP::Request::Common is used to build the POST request. Read its manual page for more info on uploading files (only filename parameter is usually required).

$vk->captcha_handler($sub)

Sets the sub to call when CAPTCHA needs to be entered. Works even when errors_noauto is true.

$vk->error

Returns the last {error} subhash received (if errors_nonfatal is true).

$vk->errors_noauto

If true, return undef instead of automatic API error handling . If this is a coderef, it will be called with the {error} subhash as the only argument. In both cases the error will be stored and will be accessible via $vk->error method.

$vk->access_token($token)

This method returns the access_token of your $vk object and sets it (if defined), allowing you to save your permament access token and use it later (when your application restarts).

AUTOLOADING

Instead of calling $vk->api(...) you can substitute the "."'s by "_"'s in the API method name and call this method on an object instead. For example,

    $vk->api("wall.post", {message => "Hello, world!"});

should be equivalent to

    $vk->wall_post({message => "Hello, world!"});

EXPORTS

None by default.

You can pass the constructor arguments to 'use Net::VKontakte::Standalone' (only hash constructor form is supported). This way it will create the $vk object for you, set up the wrappers around its methods and export them to your program (all by default). You can pass an optional parameter 'import' which should be an array reference with the list of method wrappers you need to import.

This can be useful in very small scripts or one-liners. For example,

    use Net::VKontakte::Standalone (access_token => "whatever", import => ['AUTOLOAD']);
    activity_set({text => "playing with VK API"});

BUGS

Probably many. Feel free to report my mistakes and propose changes.

Currently there is no test suite, and some features were not tested at all.

SEE ALSO

https://vk.com/dev for the list of methods and how to use them.

AUTHOR

Krylov Ivan, <krylov.r00t@gmail.com>

COPYRIGHT AND LICENSE

Copyright (C) 2012 by Krylov Ivan

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.14.2 or, at your option, any later version of Perl 5 you may have available.