.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Net::Facebook::Oauth2 3pm"
.TH Net::Facebook::Oauth2 3pm "2020-02-08" "perl v5.30.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Net::Facebook::Oauth2 \- a simple Perl wrapper around Facebook OAuth 2.0 protocol
.SH "FACEBOOK GRAPH API VERSION"
.IX Header "FACEBOOK GRAPH API VERSION"
This module complies to Facebook Graph \s-1API\s0 version 4.0, the latest
at the time of publication, \fBscheduled for deprecation not sooner than August 3rd, 2021\fR.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
Somewhere in your application's login process:
.PP
.Vb 1
\&    use Net::Facebook::Oauth2;
\&
\&    my $fb = Net::Facebook::Oauth2\->new(
\&        application_id     => \*(Aqyour_application_id\*(Aq, 
\&        application_secret => \*(Aqyour_application_secret\*(Aq,
\&        callback           => \*(Aqhttp://yourdomain.com/facebook/callback\*(Aq
\&    );
\&
\&    # get the authorization URL for your application
\&    my $url = $fb\->get_authorization_url(
\&        scope   => [ \*(Aqemail\*(Aq ],
\&        display => \*(Aqpage\*(Aq
\&    );
.Ve
.PP
Now redirect the user to this \f(CW$url\fR.
.PP
Once the user authorizes your application, Facebook will send him/her back
to your application, on the \f(CW\*(C`callback\*(C'\fR link provided above. \s-1PLEASE NOTE
THAT YOU MUST\s0 PRE-AUTHORIZE \s-1YOUR CALLBACK URI ON FACEBOOK\s0'S \s-1APP DASHBOARD.\s0
.PP
Inside that callback route, use the verifier code parameter that Facebook
sends to get the access token:
.PP
.Vb 3
\&    # param() below is a bogus function. Use whatever your web framework
\&    # provides (e.g. $c\->req\->param(\*(Aqcode\*(Aq), $cgi\->param(\*(Aqcode\*(Aq), etc)
\&    my $code = param(\*(Aqcode\*(Aq);
\&
\&    use Try::Tiny;  # or eval {}, or whatever
\&
\&    my ($unique_id, $access_token);
\&    try {
\&        $access_token = $fb\->get_access_token(code => $code); # <\-\- could die!
\&
\&        # Facebook tokens last ~2h, but you may upgrade them to ~60d if you want:
\&        $access_token = $fb\->get_long_lived_token( access_token => $access_token );
\&
\&        my $access_data = $fb\->debug_token( input => $access_token );
\&        if ($access_data && $access_data\->{is_valid}) {
\&            $unique_id = $access_data\->{user_id};
\&            # you could also check here for what scopes were granted to you
\&            # by inspecting $access_data\->{scopes}\->@*
\&        }
\&    } catch {
\&        # handle errors here!
\&    };
.Ve
.PP
If you got so far, your user is logged! Save the access token in your
database or session. As shown in the example above, Facebook also provides
a unique \fIuser_id\fR for this token so you can associate it with a particular
user of your app.
.PP
Later on you can use that access token to communicate with Facebook on behalf
of this user:
.PP
.Vb 3
\&    my $fb = Net::Facebook::Oauth2\->new(
\&        access_token => $access_token
\&    );
\&
\&    my $info = $fb\->get(
\&        \*(Aqhttps://graph.facebook.com/v4.0/me\*(Aq   # Facebook API URL
\&    );
\&
\&    print $info\->as_json;
.Ve
.PP
\&\s-1NOTE:\s0 if you skipped the call to \f(CW\*(C`debug_token()\*(C'\fR you can still find the
unique user id value with a call to the 'me' endpoint shown above, under
\&\f(CW\*(C`$info\->{id}\*(C'\fR
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Net::Facebook::Oauth2 gives you a way to simply access FaceBook Oauth 2.0
protocol.
.PP
The example folder contains some snippets you can look at, or for more
information just keep reading :)
.SH "SEE ALSO"
.IX Header "SEE ALSO"
For more information about Facebook Oauth 2.0 \s-1API\s0
.PP
Please Check
<http://developers.facebook.com/docs/>
.PP
get/post Facebook Graph \s-1API\s0
<http://developers.facebook.com/docs/api>
.SH "USAGE"
.IX Header "USAGE"
.ie n .SS """Net::Facebook::Oauth\->new( %args )"""
.el .SS "\f(CWNet::Facebook::Oauth\->new( %args )\fP"
.IX Subsection "Net::Facebook::Oauth->new( %args )"
Returns a new object to handle user authentication.
Pass arguments as a hash. The following arguments are \fI\s-1REQUIRED\s0\fR
unless you're passing an access_token (see optional arguments below):
.IP "\(bu" 4
\&\f(CW\*(C`application_id\*(C'\fR
.Sp
Your application id as you get from facebook developers platform
when you register your application
.IP "\(bu" 4
\&\f(CW\*(C`application_secret\*(C'\fR
.Sp
Your application secret id as you get from facebook developers platform
when you register your application
.PP
The following arguments are \fI\s-1OPTIONAL\s0\fR:
.IP "\(bu" 4
\&\f(CW\*(C`access_token\*(C'\fR
.Sp
If you want to instantiate an object to an existing access token, you may
do so by passing it to this argument.
.IP "\(bu" 4
\&\f(CW\*(C`browser\*(C'\fR
.Sp
The user agent that will handle requests to Facebook's \s-1API.\s0 Defaults to
LWP::UserAgent, but can be any method that implements the methods \f(CW\*(C`get\*(C'\fR,
\&\f(CW\*(C`post\*(C'\fR and \f(CW\*(C`delete\*(C'\fR and whose response to such methods implements
\&\f(CW\*(C`is_success\*(C'\fR and \f(CW\*(C`content\*(C'\fR.
.IP "\(bu" 4
\&\f(CW\*(C`display\*(C'\fR
.Sp
See \f(CW\*(C`display\*(C'\fR under the \f(CW\*(C`get_authorization_url\*(C'\fR method below.
.IP "\(bu" 4
\&\f(CW\*(C`api_version\*(C'\fR
.Sp
Use this to replace the \s-1API\s0 version on all endpoints. The default
value is 'v4.0'. Note that defining an api_version parameter together with
\&\f(CW\*(C`authorize_url\*(C'\fR, \f(CW\*(C`access_token_url\*(C'\fR or \f(CW\*(C`debug_token_url\*(C'\fR is a fatal error.
.IP "\(bu" 4
\&\f(CW\*(C`authorize_url\*(C'\fR
.Sp
Overrides the default (4.0) \s-1API\s0 endpoint for Facebook's oauth.
Used mostly for testing new versions.
.IP "\(bu" 4
\&\f(CW\*(C`access_token_url\*(C'\fR
.Sp
Overrides the default (4.0) \s-1API\s0 endpoint for Facebook's access token.
Used mostly for testing new versions.
.IP "\(bu" 4
\&\f(CW\*(C`debug_token_url\*(C'\fR
.Sp
Overrides the default (4.0) \s-1API\s0 endpoint for Facebook's token information.
Used mostly for testing new versions.
.ie n .SS """$fb\->get_authorization_url( %args )"""
.el .SS "\f(CW$fb\->get_authorization_url( %args )\fP"
.IX Subsection "$fb->get_authorization_url( %args )"
Returns an authorization \s-1URL\s0 for your application. Once you receive this
\&\s-1URL,\s0 redirect your user there in order to authorize your application.
.PP
The following argument is \fI\s-1REQUIRED\s0\fR:
.IP "\(bu" 4
\&\f(CW\*(C`callback\*(C'\fR
.Sp
.Vb 1
\&    callback => \*(Aqhttp://example.com/login/facebook/success\*(Aq
.Ve
.Sp
The callback \s-1URL,\s0 where Facebook will send users after they authorize
your application. \s-1YOU MUST CONFIRM THIS URL ON FACEBOOK\s0'S \s-1APP DASHBOARD.\s0
.Sp
To do that, go to the App Dashboard, click Facebook Login in the right-hand
menu, and check the \fBValid OAuth redirect URIs\fR in the Client OAuth Settings
section.
.PP
This method also accepts the following \fI\s-1OPTIONAL\s0\fR arguments:
.IP "\(bu" 4
\&\f(CW\*(C`scope\*(C'\fR
.Sp
.Vb 1
\&    scope => [\*(Aquser_birthday\*(Aq,\*(Aquser_friends\*(Aq, ...]
.Ve
.Sp
Array of Extended permissions as described by the Facebook Oauth \s-1API.\s0
You can get more information about scope/Extended Permission from
.Sp
<https://developers.facebook.com/docs/facebook\-login/permissions/>
.Sp
Please note that requesting information other than \f(CW\*(C`name\*(C'\fR, \f(CW\*(C`email\*(C'\fR and
\&\f(CW\*(C`profile_picture\*(C'\fR \fBwill require your app to be reviewed by Facebook!\fR
.IP "\(bu" 4
\&\f(CW\*(C`state\*(C'\fR
.Sp
.Vb 1
\&    state => \*(Aq123456abcde\*(Aq
.Ve
.Sp
An arbitrary unique string provided by you to guard against Cross-site Request
Forgery. This value will be returned to you by Facebook, unchanged. Note that,
as of Facebook \s-1API\s0 v3.0, this argument is \fImandatory\fR, so if you don't
provide a 'state' argument, we will default to \f(CW\*(C`time()\*(C'\fR.
.IP "\(bu" 4
\&\f(CW\*(C`auth_type\*(C'\fR
.Sp
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 \f(CW\*(Aqrerequest\*(Aq\fR to explicitly tell the dialog
you're re-asking for a declined permission.
.IP "\(bu" 4
\&\f(CW\*(C`display\*(C'\fR
.Sp
.Vb 1
\&    display => \*(Aqpage\*(Aq
.Ve
.Sp
How to display Facebook Authorization page. Defaults to \f(CW\*(C`page\*(C'\fR.
Can be any of the following:
.RS 4
.IP "\(bu" 4
\&\f(CW\*(C`page\*(C'\fR
.Sp
This will display facebook authorization page as full page
.IP "\(bu" 4
\&\f(CW\*(C`popup\*(C'\fR
.Sp
This option is useful if you want to popup authorization page
as this option tell facebook to reduce the size of the authorization page
.IP "\(bu" 4
\&\f(CW\*(C`wab\*(C'\fR
.Sp
From the name, for wab and mobile applications this option is the best, as
the facebook authorization page will fit there :)
.RE
.RS 4
.RE
.IP "\(bu" 4
\&\f(CW\*(C`response_type\*(C'\fR
.Sp
.Vb 1
\&    response_type => \*(Aqcode\*(Aq
.Ve
.Sp
When the redirect back to the app occurs, determines whether the response
data is in \s-1URL\s0 parameters or fragments. Defaults to \f(CW\*(C`code\*(C'\fR, 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
\&\f(CW\*(C`token\*(C'\fR, \f(CW\*(C`code%20token\*(C'\fR, or \f(CW\*(C`granted_scopes\*(C'\fR. Note that changing this to
anything other than 'code' might change the login flow described in this
documentation, rendering calls to \f(CW\*(C`get_access_token()\*(C'\fR pointless.
Please see
Facebook's login documentation <https://developers.facebook.com/docs/facebook-login/manually-build-a-login-flow>
for more information.
.ie n .SS """$fb\->get_access_token( %args )"""
.el .SS "\f(CW$fb\->get_access_token( %args )\fP"
.IX Subsection "$fb->get_access_token( %args )"
This method issues a \s-1GET\s0 request to Facebook's \s-1API\s0 to retrieve the
access token string for the specified code (passed as an argument).
.PP
Returns the access token string or raises an exception in case of errors
(\fBmake sure to trap calls with eval blocks or a try/catch module\fR). Note
that Facebook's access tokens are short-lived, around 2h of idle time
before expiring. If you want to \*(L"upgrade\*(R" the token to a long lived one
(with around 60 days of idle time), use this token to feed the
\&\f(CW\*(C`get_long_lived_token()\*(C'\fR method.
.PP
You should call this method inside the route for the callback \s-1URI\s0 defined
in the \f(CW\*(C`get_authorization_url\*(C'\fR method. It receives the following arguments:
.IP "\(bu" 4
\&\f(CW\*(C`code\*(C'\fR
.Sp
This is the verifier code that Facebook sends back to your
callback \s-1URL\s0 once user authorize your app, you need to capture
this code and pass to this method in order to get the access token.
.Sp
Verifier code will be presented with your callback \s-1URL\s0 as code
parameter as the following:
.Sp
http://your\-call\-back\-url.com?code=234er7y6fdgjdssgfsd...
.Sp
Note that if you have fiddled with the \f(CW\*(C`response_type\*(C'\fR argument,
you might not get this parameter properly.
.PP
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 \s-1API\s0 requests to Facebook on their behalf.
.PP
To know \fI\s-1WHICH\s0\fR 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.
.PP
This was usually done by making a \s-1GET\s0 request to the \f(CW\*(C`me\*(C'\fR \s-1API\s0 endpoint and
looking for the 'id' field. However, Facebook has introduced a new endpoint
for that flow that returns the id (this time as 'user_id') and some extra
validation data, like whether the token is valid, to which app it refers to,
what scopes the user agreed to, etc, so now you are encouraged to call the
\&\f(CW\*(C`debug_token()\*(C'\fR method as shown in the \s-1SYNOPSIS.\s0
.PP
\&\fB\s-1IMPORTANT:\s0\fR 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.
.ie n .SS """$fb\->get_long_lived_token( access_token => $access_token )"""
.el .SS "\f(CW$fb\->get_long_lived_token( access_token => $access_token )\fP"
.IX Subsection "$fb->get_long_lived_token( access_token => $access_token )"
Asks facebook to retrieve the long-lived (~60d) version of the provided
short-lived (~2h) access token retrieved from \f(CW\*(C`get_access_token()\*(C'\fR. If
successful, this method will return the long-lived token, which you can
use to replace the short-lived one. Otherwise, it croaks with an error
message, in which case you can continue to use the short-lived version.
.PP
See here <https://developers.facebook.com/docs/facebook-login/access-tokens/refreshing>
for the gory details.
.ie n .SS """$fb\->debug_token( input => $access_token )"""
.el .SS "\f(CW$fb\->debug_token( input => $access_token )\fP"
.IX Subsection "$fb->debug_token( input => $access_token )"
This method should be called right after \f(CW\*(C`get_access_token()\*(C'\fR. It will
query Facebook for details about the given access token and validate that
it was indeed granted to your app (and not someone else's).
.PP
It requires a single argument, \f(CW\*(C`input\*(C'\fR, containing the access code obtained
from calling \f(CW\*(C`get_access_token\*(C'\fR.
.PP
It croaks on HTTP/connection/Facebook errors, returns nothing if for whatever
reason the response is invalid without errors (e.g. no app_id and no user_id),
and also if the returned app_id is not the same as your own application_id
(pass a true value to \f(CW\*(C`skip_check\*(C'\fR to skip this validation).
.PP
If all goes well, it returns a hashref with the \s-1JSON\s0 structure returned by
Facebook.
.ie n .SS """$fb\->get( $url, $args )"""
.el .SS "\f(CW$fb\->get( $url, $args )\fP"
.IX Subsection "$fb->get( $url, $args )"
Sends a \s-1GET\s0 request to Facebook and stores the response in the given object.
.IP "\(bu" 4
\&\f(CW\*(C`url\*(C'\fR
.Sp
Facebook Graph \s-1API URL\s0 as string. You must provide the full \s-1URL.\s0
.IP "\(bu" 4
\&\f(CW$args\fR
.Sp
hashref of parameters to be sent with graph \s-1API URL\s0 if required.
.PP
You can access the response using the following methods:
.IP "\(bu" 4
\&\f(CW\*(C`$response>as_json\*(C'\fR
.Sp
Returns response as json object
.IP "\(bu" 4
\&\f(CW\*(C`$response>as_hash\*(C'\fR
.Sp
Returns response as perl hashref
.PP
For more information about facebook graph \s-1API,\s0 please check
http://developers.facebook.com/docs/api
.ie n .SS """$fb\->post( $url, $args )"""
.el .SS "\f(CW$fb\->post( $url, $args )\fP"
.IX Subsection "$fb->post( $url, $args )"
Send a \s-1POST\s0 request to Facebook and stores the response in the given object.
See the \f(CW\*(C`as_hash\*(C'\fR and \f(CW\*(C`as_json\*(C'\fR methods above for how to retrieve the
response.
.IP "\(bu" 4
\&\f(CW\*(C`url\*(C'\fR
.Sp
Facebook Graph \s-1API URL\s0 as string
.IP "\(bu" 4
\&\f(CW$args\fR
.Sp
hashref of parameters to be sent with graph \s-1API URL\s0
.PP
For more information about facebook graph \s-1API,\s0 please check
<http://developers.facebook.com/docs/api>
.ie n .SS """$fb\->delete( $url, $args )"""
.el .SS "\f(CW$fb\->delete( $url, $args )\fP"
.IX Subsection "$fb->delete( $url, $args )"
Send a \s-1DELETE\s0 request to Facebook and stores the response in the given object.
See the \f(CW\*(C`as_hash\*(C'\fR and \f(CW\*(C`as_json\*(C'\fR methods above for how to retrieve the
response.
.IP "\(bu" 4
\&\f(CW\*(C`url\*(C'\fR
.Sp
Facebook Graph \s-1API URL\s0 as string
.IP "\(bu" 4
\&\f(CW$args\fR
.Sp
hashref of parameters to be sent with graph \s-1API URL\s0
.SH "AUTHOR"
.IX Header "AUTHOR"
Mahmoud A. Mehyar, <mamod.mehyar@gmail.com>
.SH "CONTRIBUTORS"
.IX Header "CONTRIBUTORS"
Big Thanks To
.IP "\(bu" 4
Takatsugu Shigeta \f(CW@comewalk\fR <https://github.com/comewalk>
.IP "\(bu" 4
Breno G. de Oliveira \f(CW@garu\fR <https://github.com/garu>
.IP "\(bu" 4
squinker \f(CW@squinker\fR <https://github.com/squinker>
.IP "\(bu" 4
Valcho Nedelchev \f(CW@valchonedelchev\fR <https://github.com/valchonedelchev>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (C) 2012\-2019 by Mahmoud A. Mehyar
.PP
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.