Ubuntu Manpage: Net::Facebook::Oauth2 - a simple Perl wrapper around Facebook OAuth v2.0 protocol

Provided by: libnet-facebook-oauth2-perl_0.10-1_all

NAME

       Net::Facebook::Oauth2 - a simple Perl wrapper around Facebook OAuth v2.0 protocol

FACEBOOK GRAPH API VERSION

       This module complies to Facebook Graph API version 2.8, the latest at the time of
       publication, scheduled for deprecation on October 5th, 2018.

       One month prior to that, using this version of Net::Facebook::Oauth2 will trigger a
       warning message.

SYNOPSIS

       Somewhere in your application's login process:

           use Net::Facebook::Oauth2;

           my $fb = Net::Facebook::Oauth2->new(
               application_id     => 'your_application_id',
               application_secret => 'your_application_secret',
               callback           => 'http://yourdomain.com/facebook/callback'
           );

           # get the authorization URL for your application
           my $url = $fb->get_authorization_url(
               scope   => [ 'public_profile', 'email', 'user_about_me', 'manage_pages' ],
               display => 'page'
           );

       Now redirect the user to this $url.

       Once the user authorizes your application, Facebook will send him/her back to your
       application, on the "callback" link provided above. PLEASE NOTE THAT YOU MUST PRE-
       AUTHORIZE YOUR CALLBACK URI ON FACEBOOK'S APP DASHBOARD.

       Inside that callback route, use the verifier code parameter that Facebook sends to get the
       access token:

           # param() below is a bogus function. Use whatever your web framework
           # provides (e.g. $c->req->param('code'), $cgi->param('code'), etc)
           my $code = param('code');

           my $access_token = $fb->get_access_token(code => $code);

       If you got so far, your user is logged! Save this access token in your database or
       session.

       Later on you can use that access token to communicate with Facebook on behalf of this
       user:

           my $fb = Net::Facebook::Oauth2->new(
               access_token => $access_token
           );

           my $info = $fb->get(
               'https://graph.facebook.com/v2.8/me'   # Facebook API URL
           );

           print $info->as_json;

DESCRIPTION

       Net::Facebook::Oauth2 gives you a way to simply access FaceBook Oauth 2.0 protocol

       For more information please see example folder shipped with this Module

USAGE

"Net::Facebook::Oauth->new( %args )"
Returns a new object to handle user authentication. Pass arguments as a hash. The
following arguments are REQUIRED unless you're passing an access_token (see optional
arguments below):

• "application_id"

Your application id as you get from facebook developers platform when you register
your application

• "application_secret"

Your application secret id as you get from facebook developers platform when you
register your application

The following arguments are OPTIONAL:

• "access_token"

If you want to instantiate an object to an existing access token, you may do so by
passing it to this argument.

• "browser"

The user agent that will handle requests to Facebook's API. Defaults to
LWP::UserAgent, but can be any method that implements the methods "get", "post" and
"delete" and whose response to such methods implements "is_success" and "content".

• "display"

See "display" under the "get_authorization_url" method below.

• "authorize_url"

Overrides the default (2.8) API endpoint for Facebook's oauth. Used mostly for
testing new versions.

• "access_token_url"

Overrides the default (2.8) API endpoint for Facebook's access token. Used mostly for
testing new versions.

• "auth_type"

When a user declines a given permission, you must reauthorize them. But when you do
so, any previously declined permissions will not be asked again by Facebook. Set this
argument to 'rerequest' to explicitly tell the dialog you're re-asking for a declined
permission.

"$fb->get_authorization_url( %args )"
Returns an authorization URL for your application. Once you receive this URL, redirect
your user there in order to authorize your application.

The following argument is REQUIRED:

• "callback"

callback => 'http://example.com/login/facebook/success'

The callback URL, where Facebook will send users after they authorize your
application. YOU MUST CONFIRM THIS URL ON FACEBOOK'S APP DASHBOARD.

To do that, go to the App Dashboard, click Facebook Login in the right-hand menu, and
check the Valid OAuth redirect URIs in the Client OAuth Settings section.

This method also accepts the following OPTIONAL arguments:

• "scope"

scope => ['user_events','manage_pages', ...]

Array of Extended permissions as described by facebook Oauth API. You can get more
information about scope/Extended Permission from

<https://developers.facebook.com/docs/facebook-login/permissions/>

Please note that requesting information other than "public_profile", "email" and
"user_friends" will require your app to be reviewed by Facebook!

• "state"

state => '123456abcde'

An arbitrary unique string provided by you to guard against Cross-site Request
Forgery.

• "display"

display => 'page'

How to display Facebook Authorization page. Defaults to "page". Can be any of the
following:

• "page"

This will display facebook authorization page as full page

• "popup"

This option is useful if you want to popup authorization page as this option tell
facebook to reduce the size of the authorization page

• "wab"

From the name, for wab and mobile applications this option is the best facebook
authorization page will fit there :)

• "response_type"

response_type => 'code'

When the redirect back to the app occurs, determines whether the response data is in
URL parameters or fragments. Defaults to "code", which is Facebook's default and
useful for cases where the server handles the token (which is most likely why you are
using this module), but can be also be "token", "code%20token", or "granted_scopes".
Please see Facebook's login documentation
<https://developers.facebook.com/docs/facebook-login/manually-build-a-login-flow> for
more information.

"$fb->get_access_token( %args )"
This method issues a GET request to Facebook's API to retrieve the access token string for
the specified code (passed as an argument).

Returns the access token string or raises an exception in case of errors.

You should call this method inside the route for the callback URI defined in the
"get_authorization_url" method. It receives the following arguments:

• "code"

This is the verifier code that Facebook sends back to your callback URL once user
authorize your app, you need to capture this code and pass to this method in order to
get the access token.

Verifier code will be presented with your callback URL as code parameter as the
following:

http://your-call-back-url.com?code=234er7y6fdgjdssgfsd...

Note that if you have fiddled with the "response_type" argument, you might not get
this parameter properly.

When the access token is returned you need to save it in a secure place in order to use it
later in your application. The token indicates that a user has authorized your site/app,
meaning you can associate that token to that user and issue API requests to Facebook on
their behalf.

To know WHICH user has granted you the authorization (e.g. when building a login system to
associate that token with a unique user on your database), you must make a request to
fetch Facebook's own unique identifier for that user, and then associate your own user's
unique id to Facebook's. This is usually done by making a GET request to the "me" API
endpoint, as shown in the SYNOPSIS.

IMPORTANT: Expect that the length of all access token types will change over time as
Facebook makes changes to what is stored in them and how they are encoded. You can expect
that they will grow and shrink over time. Please use a variable length data type without
a specific maximum size to store access tokens.

"$fb->get( $url, $args )"
Sends a GET request to Facebook and stores the response in the given object.

• "url"

Facebook Graph API URL as string. You must provide the full URL.

• $args

hashref of parameters to be sent with graph API URL if required.

You can access the response using the following methods:

• "$response>as_json"

Returns response as json object

• "$response>as_hash"

Returns response as perl hashref

For more information about facebook graph API, please check
http://developers.facebook.com/docs/api

"$fb->post( $url, $args )"
Send a POST request to Facebook and stores the response in the given object. See the
"as_hash" and "as_json" methods above for how to retrieve the response.

• "url"

Facebook Graph API URL as string

• $args

hashref of parameters to be sent with graph API URL

For more information about facebook graph API, please check
<http://developers.facebook.com/docs/api>

"$fb->delete( $url, $args )"
Send a DELETE request to Facebook and stores the response in the given object. See the
"as_hash" and "as_json" methods above for how to retrieve the response.

• "url"

Facebook Graph API URL as string

• $args

hashref of parameters to be sent with graph API URL

AUTHOR

       Mahmoud A. Mehyar, <mamod.mehyar@gmail.com>

CONTRIBUTORS

       Big Thanks To

       •   Takatsugu Shigeta @comewalk <https://github.com/comewalk>

       •   Breno G. de Oliveira @garu <https://github.com/garu>

       •   squinker @squinker <https://github.com/squinker>

       •   Valcho Nedelchev @valchonedelchev <https://github.com/valchonedelchev>

COPYRIGHT AND LICENSE

       Copyright (C) 2012-2016 by Mahmoud A. Mehyar

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

NAME

FACEBOOK GRAPH API VERSION

SYNOPSIS

DESCRIPTION

SEE ALSO

USAGE

AUTHOR

CONTRIBUTORS

COPYRIGHT AND LICENSE