Facebook-OpenGraph
view release on metacpan or search on metacpan
[](https://travis-ci.org/oklahomer/p5-Facebook-OpenGraph) [;
my $page = $fb->fetch('oklahomer.docs');
my $objs = $fb->bulk_fetch([qw/zuck oklahomer.docs/]);
# get access_token for application
my $token_ref = Facebook::OpenGraph->new(+{
app_id => 12345,
secret => 'FooBarBuzz',
})->get_app_token;
# user authorization
my $fb = Facebook::OpenGraph->new(+{
app_id => 12345,
secret => 'FooBarBuzz',
namespace => 'my_app_namespace',
redirect_uri => 'https://sample.com/auth_callback',
});
my $auth_url = $fb->auth_uri(+{
scope => [qw/email publish_actions/],
});
$c->redirect($auth_url);
my $req = Plack::Request->new($env);
my $token_ref = $fb->get_user_token_by_code($req->query_param('code'));
$fb->set_access_token($token_ref->{access_token});
# publish photo
$fb->publish('/me/photos', +{
source => '/path/to/pic.png',
message => 'Hello world!',
});
# publish Open Graph Action
$fb->publish_action($action_type, +{$object_type => $object_url});
# DESCRIPTION
Facebook::OpenGraph is a Perl interface to handle Facebook's Graph API.
This module is inspired by [Facebook::Graph](https://metacpan.org/pod/Facebook::Graph), but mainly focuses on simplicity
and customizability because we must be able to keep up with frequently changing
API specification.
This module does **NOT** provide ways to set and validate parameters for each
API endpoint like Facebook::Graph does with Any::Moose. Instead it provides
some basic methods for HTTP request. It also provides some handy methods that
wrap `request()` for you to easily utilize most of Graph API's functionalities
including:
- API versioning that was introduced at f8, 2014.
- Acquiring user, app and/or page token and refreshing user token for
long lived one.
- Batch Request
- FQL
- FQL with Multi-Query
- Field Expansion
- Etag
- Wall Posting with Photo or Video
- Creating Test Users
- Checking and Updating Open Graph Object or Web Page with OGP
- Publishing Open Graph Action
- Deleting Open Graph Object
- Posting Staging Resource for Open Graph Object
In most cases you can specify endpoints and request parameters by yourself and
pass them to request() so it should be easier to test latest API specs. Other
requesting methods merely wrap request() method for convinience.
# METHODS
## Class Methods
### `Facebook::OpenGraph->new(\%args)`
Creates and returns a new Facebook::OpenGraph object.
_%args_ can contain...
- app\_id
Facebook application ID. app\_id and secret are required to get application
access token. Your app\_id should be obtained from
[https://developers.facebook.com/apps/](https://developers.facebook.com/apps/).
- secret
Facebook application secret. It should be obtained from
[https://developers.facebook.com/apps/](https://developers.facebook.com/apps/).
- version
This declares Facebook Platform version. From 2014-04-30 they support versioning
and migrations. Default value is undef because unversioned API access is also
allowed. This value is prepended to the end point on `request()` unless
you specify one in requesting path.
my $fb = Facebook::OpenGraph->new(+{version => 'v2.0'});
$fb->get('/zuck'); # Use version 2.0 by accessing /v2.0/zuck
$fb->get('/v1.0/zuck'); # Ignore the default version and use version 1.0
my $fb = Facebook::OpenGraph->new();
$fb->get('/zuck'); # Unversioned API access since version is not specified
# on initialisation or reqeust.
As of 2015-03-29, the latest version is v2.3. Detailed information should be
found at [https://developers.facebook.com/docs/apps/versions](https://developers.facebook.com/docs/apps/versions) and
[https://developers.facebook.com/docs/apps/migrations](https://developers.facebook.com/docs/apps/migrations).
- ua
This should be [Furl::HTTP](https://metacpan.org/pod/Furl::HTTP) object or similar object that provides same
interface. Default is equivalent to Furl::HTTP->new(capture\_request => 1).
You **SHOULD** install 2.10 or later version of Furl to enable capture\_request
option. Or you can specify keep\_request option for same purpose if you have Furl
2.09. Setting capture\_request option is **strongly** recommended since it gives
you the request headers and content when `request()` fails.
my $fb = Facebook::OpenGraph->new;
$fb->post('/me/feed', +{message => 'Hello, world!'});
#2500:- OAuthException:An active access token must be used to query information about the current user.
#POST /me/feed HTTP/1.1
#Connection: keep-alive
#User-Agent: Furl::HTTP/2.15
#Content-Type: application/x-www-form-urlencoded
#Content-Length: 27
then queries are divided into multiple batch requests, and responses are
combined so it just seems like a single batch request. Default value is 50 as
API documentation says.
### `$fb->is_beta`
Accessor method that returns whether to use Beta tier or not.
### `$fb->json`
Accessor method that returns JSON object. This object will be passed to
Facebook::OpenGraph::Response via `create_response()`.
### `$fb->use_appsecret_proof`
Accessor method that returns whether to send appsecret\_proof parameter on API
call. Official document is not provided yet, but PHP SDK has this option and
you can activate this option from App Setting > Advanced > Security.
### `$fb->use_post_method`
Accessor method that returns whether to use POST method for every API call and
alternatively set method=(GET|POST|DELETE) query parameter. PHP SDK works this
way. This might work well when you use multi-query or some other functions that use GET method while query string can be very long and you have to worry about
the maximum length of it.
### `$fb->version`
Accessor method that returns Facebook Platform version. This can be undef
unless you explicitly on initialisation.
### `$fb->uri($path, \%query_param)`
Returns URI object with specified path and query parameter. If is\_beta returns
true, the base url is https://graph.beta.facebook.com/ . Otherwise its base url
is https://graph.facebook.com/ . `request()` automatically determines if it
should use `uri()` or `video_uri()` based on target path and parameters so
you won't use `uri()` or `video_uri()` directly as long as you are using
requesting methods that are provided in this module.
### `$fb->video_uri($path, \%query_param)`
Returns URI object with specified path and query parameter. This should only be
used when posting a video.
### `$fb->site_uri($path, \%query_param)`
Returns URI object with specified path and query parameter. It is mainly used to
generate URL for Auth dialog, but you can still use this when redirecting users
to your Facebook page, App's Canvas page or any location on facebook.com.
my $fb = Facebook::OpenGraph->new(+{is_beta => 1});
$c->redirect($fb->site_uri($path_to_canvas));
# https://www.beta.facebook.com/$path_to_canvas
### `$fb->parse_signed_request($signed_request_str)`
It parses signed\_request that Facebook Platform gives to you on various
situations. situations may include
- Given as a URL fragment on callback endpoint after login flow is done
with Login Dialog
- POSTed when Page Tab App is loaded
- Set in a form of cookie by JS SDK
Fields in returning value are introduced at
[https://developers.facebook.com/docs/reference/login/signed-request/](https://developers.facebook.com/docs/reference/login/signed-request/).
my $req = Plack::Request->new($env);
my $val = $fb->parse_signed_request($req->query_param('signed_request'));
### `$fb->auth_uri(\%args)`
Returns URL for Facebook OAuth dialog. You can redirect your user to this
URL for authorization purpose.
If Facebook Platform version is set on initialisation, that value is
prepended to the path.
[https://developers.facebook.com/docs/apps/versions#dialogs](https://developers.facebook.com/docs/apps/versions#dialogs).
See the detailed flow at [https://developers.facebook.com/docs/facebook-login/manually-build-a-login-flow](https://developers.facebook.com/docs/facebook-login/manually-build-a-login-flow).
Optional values are shown at [https://developers.facebook.com/docs/reference/dialogs/oauth/](https://developers.facebook.com/docs/reference/dialogs/oauth/).
my $auth_url = $fb->auth_uri(+{
display => 'page', # Dialog's display type. Default value is 'page.'
response_type => 'code',
scope => [qw/email publish_actions/],
});
$c->redirect($auth_url);
### `$fb->set_access_token($access_token)`
Set $access\_token as the access token to be used on `request()`. `access_token()`
returns this value.
### `$fb->get_app_token`
Obtain an access token for application. Give the returning value to
`set_access_token()` and you can make request on behalf of your application.
This access token never expires unless you reset application secret key on App
Dashboard so you might want to store this value within your process like
below...
package MyApp::OpenGraph;
use parent 'Facebook::OpenGraph';
sub get_app_token {
my $self = shift;
return $self->{__app_access_token__}
||= $self->SUPER::get_app_token->{access_token};
}
Or you might want to use [Cache::Memory::Simple](https://metacpan.org/pod/Cache::Memory::Simple) or something similar to
refetch token at an interval of your choice. Maybe you want to store token on
DB and override this method to return the stored value.
### `$fb->get_user_token_by_code($given_code)`
Obtain an access token for user based on `$code`. `$code` should be obtained
on your callback endpoint which is specified on `eredirect_uri`. Give the
returning access token to `set_access_token()` and you can act on behalf of
the user.
FYI: _expires_ or _expires\_in_ is **NOT** returned on some edge cases. The
detail and reproductive scenario should be found at
[https://developers.facebook.com/bugs/597779113651383/](https://developers.facebook.com/bugs/597779113651383/).
# On OAuth callback page which you specified on $fb->redirect_uri.
my $req = Plack::Request->new($env);
my $token_ref = $fb->get_user_token_by_code($req->query_param('code'));
my $access_token = $token_ref->{access_token};
my $expires = $token_ref->{expires}; # named expires_in as of v2.3
### `$fb->get_user_token_by_cookie($cookie_value)`
Obtain user access token based on the cookie value that is set by JS SDK.
Cookie name should be determined with `js_cookie_name()`.
FYI: _expires_ or _expires\_in_ is **NOT** returned on some edge cases. The
detail and reproductive schenario should be found at
[https://developers.facebook.com/bugs/597779113651383/](https://developers.facebook.com/bugs/597779113651383/).
if (my $cookie = $c->req->cookie( $fb->js_cookie_name )) {
# User is not logged in yet, but cookie is set by JS SDK on previous visit.
my $token_ref = $fb->get_user_token_by_cookie($cookie);
# {
# "access_token" : "new_token_string_qwerty",
# "expires" : 5752 # named expires_in as of v2.3
# };
}
else {
return $c->redirect( $fb->auth_uri );
}
### `$fb->exchange_token($short_term_token)`
Exchange short lived access token for long lived one. Short lived tokens are
ones that you obtain with `get_user_token_by_code()`. Usually long lived
tokens live about 60 days while short lived ones live about 2 hours.
FYI: _expires_ or _expires\_in_ is **NOT** returned on some edge cases. The
detail and reproductive schenario should be found at
[https://developers.facebook.com/bugs/597779113651383/](https://developers.facebook.com/bugs/597779113651383/).
my $extended_token_ref = $fb->exchange_token($token_ref->{access_token});
my $access_token = $extended_token_ref->{access_token};
my $expires = $extended_token_ref->{expires};
# named expires_in as of v2.3
If you loved the way old offline\_access permission worked, and are looking for a
substitute you might want to try this.
### `$fb->get($path, \%param, \@headers)`
Alias to `request()` that sends `GET` request.
my $path = 'zuck'; # should be ID or username
my $user = $fb->get($path);
#{
# name => 'Mark Zuckerberg',
Generates and returns the name of cookie that is set by JS SDK on client side
login. This value can be parsed as signed request and the parsed data structure
contains 'code' to exchange for acess token. See `get_user_token_by_cookie()`
for detail.
### `$fb->create_response($http_status_code, $http_status_message, \@response_headers, $response_content)`
Creates and returns [Facebook::OpenGraph::Response](https://metacpan.org/pod/Facebook::OpenGraph::Response). If you wish to use
customized response class, then override this method to return
MyApp::Better::Response.
### `$fb->prep_param(\%param)`
Handles sending parameters and format them in the way Graph API spec states.
This method is called in `request()` so you don't usually use this method
directly.
### `$fb->prep_fields_recursive(\@fields)`
Handles fields parameter and format it in the way Graph API spec states.
The main purpose of this method is to deal with Field Expansion
([https://developers.facebook.com/docs/graph-api/using-graph-api/#fieldexpansion](https://developers.facebook.com/docs/graph-api/using-graph-api/#fieldexpansion)).
This method is called in `prep_param` which is called in `request()` so you
don't usually use this method directly.
# simple fields
$fb->prep_fields_recursive([qw/name email albums/]); # name,email,albums
# use field expansion
$fb->prep_fields_recursive([
'name',
'email',
+{
albums => +{
fields => [
'name',
+{
photos => +{
fields => [
'name',
'picture',
+{
tags => +{
limit => 2,
},
}
],
limit => 3,
}
}
],
limit => 5,
}
}
]);
# 'name,email,albums.fields(name,photos.fields(name,picture,tags.limit(2)).limit(3)).limit(5)'
### `$fb->publish_action($action_type, \%param)`
Alias to `request()` that optimizes body content and endpoint to send `POST`
request to publish Open Graph Action.
my $res = $fb->publish_action('give', +{crap => 'https://sample.com/poop/'});
#{id => 123456}
### `$fb->create_test_users(\@settings)`
my $res = $fb->create_test_users([
+{
permissions => [qw/publish_actions/],
locale => 'en_US',
installed => 'true',
},
+{
permissions => [qw/publish_actions email read_stream/],
locale => 'ja_JP',
installed => 'true',
}
])
#[
# +{
# id => 123456789,
# access_token => '5678uiop',
# login_url => 'https://www.facebook.com/........',
# email => '.....@tfbnw.net',
# password => '.......',
# },
# +{
# id => 1234567890,
# access_token => '5678uiopasadfasdfa',
# login_url => 'https://www.facebook.com/........',
# email => '.....@tfbnw.net',
# password => '.......',
# },
#];
Alias to `request()` that optimizes to create test users for your application.
### `$fb->publish_staging_resource($file_path)`
Alias to `request()` that optimizes body content to send `POST` request to upload image to Object API's staging environment.
my $fb = Facebook::OpenGraph->new(+{
access_token => $USER_ACCESS_TOKEN,
});
my $res = $fb->publish_staging_resource('/path/to/file');
#{
# uri => 'fbstaging://graph.facebook.com/staging_resources/MDExMzc3MDU0MDg1ODQ3OTY2OjE5MDU4NTM1MzQ=',
#};
### `$fb->check_object($object_id_or_url)`
Alias to `request()` that sends `POST` request to Facebook Debugger to
check/update object.
$fb->check_object('https://sample.com/object/');
$fb->check_object($object_id);
# AUTHOR
( run in 0.596 second using v1.01-cache-2.11-cpan-39bf76dae61 )