NAME

Facebook::OAuth - Extends Google::OAuth for Facebook

SYNOPSIS

use Facebook::OAuth;
use base qw( Google::OAuth ) ;

## Get Grant Code
$link = Facebook::OAuth->new->scope( ... )->token_request ;
$link = Facebook::OAuth->token_request ;		## use defaults

## Generate Token
Facebook::OAuth->grant_code( $code ) ;

## Access Facebook
$fbo = Facebook::OAuth->token( $email )->content( GET => $url ) ;
$fbo = Facebook::OAuth->token( $email )->content( $url ) ;

DESCRIPTION

Facebooks's OAuth implementation is much simpler than Google's, so this interface may be over-generalized. The advantage lies in code reuse, and a consistent interface that ultimately provides an effective general purpose OAuth client.

The Google::OAuth setup includes a Facebook configuration to establish Facebook credentials. The configuration assumes a single data source for all OAuth tokens that can support a variety of web services.

Additionally, the SYNOPSIS demonstrates an API showing the 3 phases of data access:

Acquire a Grant Code

In order to generate a Grant Code, users log into Facebook and the grant code is transmitted to a redirect_uri defined in the credentials. All the credentials are passed as query parameters in a single URI link.

Facebook uses quite a few permission settings, any number of which can be passed as arguments to the scope() method. This interface always requests the email permisssion.

## Get Grant Code
$link = Facebook::OAuth->token_request ;

Acquire a Token

Facebook returns a temporary grant code that needs to be resubmitted to obtain a token. The grant code is transmitted to a webserver via the redirect_uri so the token is usually acquired by a process owned by the webserver.

## Generate Token
Facebook::OAuth->grant_code( $code ) ;

The grant_code method saves the results in the data source. Since it normally returns a volatile object, the following invocation is recommended to examine the results:

%status = %{ Facebook::OAuth->grant_code( $code, $email ) } ;

Refresh Token - Access Facebook

A Facebook token can be renewed indefinitely, but the expiration policy is Use it or lose it. Google requires that a token be renewed before using. Use the same approach to ensure that a Facebook token is continuously renewed as follows:

## $fobj - Facebook data object 
## $url - Use Facebook API

$fobj = Facebook::OAuth->token( $email )->content( GET => $url ) ;

## If necessary, select an email key from a list:

@email = Facebook::OAuth->token_list ;

## If the token is to be reused:

$token = Facebook::OAuth->token( $email ) ;
$fobj = $token->content( GET => $url ) ;

## GET is the default method, so the following works:
$fobj = $token->content( $url ) ;

METHODS

The following methods are overridden in the Facebook::OAuth subclass:

setclient()

setclient() replaces the Google configuration parameters with their Facebook equivalents.

classID()

classID() returns constant integer 1.

grant_type()

grant_type() returns constant string 'fb_exchange_token'.

scope()

Facebook permissions are defined as simple terms so these are not predefined in the package as Google's are. Any permission value can be used. See Facebook's documentation https://developers.facebook.com/docs/reference/login/#permissions.

Additionally, terms are represented differently in the URI. And finally, scope() defines a default appropriate for Facebook.

token_request()

The overridden token_request() method replaces the built in URI link and requires few arguments than Google.

grant_code()

grant_code() is overloaded to define its own process for determining the email key. If necessary, one can be manually assigned as a method argument.

get_token()

get_token() has a few differences with the superclass Google::OAuth method:

The target URL (Facebook versus Google) is built into the method definition.

Facebook uses an HTTP GET request instead of a POST.

Facebook does not return JSON when a token request succeeds.

The overridden method copies the token into an element named fb_exchange_token.

expired()

expired() uses the Facebook token element named expires.

headers()

The overridden headers() method has no body because Facebook has no special header requirements.

request()

The request() method is overridden to append the token as a query parameter to the URL argument. In Google::OAuth, the token is passed as an HTTP header.

EXPORT

None by default.

SEE ALSO

Google::OAuth

AUTHOR

Jim Schueler, <jim@tqis.com>

COPYRIGHT AND LICENSE

Copyright (C) 2013 by Jim Schueler

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

cpanm Google::OAuth

perl -MCPAN -e shell
install Google::OAuth