view release on metacpan or  search on metacpan

lib/Facebook/OpenGraph.pm  view on Meta::CPAN

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.

=head1 METHODS

=head2 Class Methods

=head3 C<< Facebook::OpenGraph->new(\%args) >>

Creates and returns a new Facebook::OpenGraph object.

I<%args> can contain...

=over 4

=item * app_id

Facebook application ID. app_id and secret are required to get application
access token. Your app_id should be obtained from
L<https://developers.facebook.com/apps/>.

=item * secret

Facebook application secret. It should be obtained from
L<https://developers.facebook.com/apps/>.

=item * 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 C<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 L<https://developers.facebook.com/docs/apps/versions> and
L<https://developers.facebook.com/docs/apps/migrations>.

=item * ua

This should be L<Furl::HTTP> object or similar object that provides same
interface. Default is equivalent to Furl::HTTP->new(capture_request => 1).
You B<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 B<strongly> recommended since it gives
you the request headers and content when C<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
  #Host: graph.facebook.com
  #
  #message=Hello%2C%20world%21

=item * namespace

Facebook application namespace. This is used when you publish Open Graph Action
via C<publish_action()>.

=item * access_token

Access token for user, application or Facebook Page.

=item * redirect_uri

The URL to be used for authorization. User will be redirected to this URL after
login dialog. Detail should be found at
L<https://developers.facebook.com/docs/reference/dialogs/oauth/>.

You must keep in mind that "The URL you specify must be a URL with the same
base domain specified in your app's settings, a Canvas URL of the form
https://apps.facebook.com/YOUR_APP_NAMESPACE or a Page Tab URL of the form
https://www.facebook.com/PAGE_USERNAME/app_YOUR_APP_ID"

=item * batch_limit

The maximum number of queries that can be set within a single batch request.
If the number of given queries exceeds this, then queries are divided into
multiple batch requests, and responses are combined so it seems just like a
single request.

Default value is 50 as API documentation says. Official documentation is
located at L<https://developers.facebook.com/docs/graph-api/making-multiple-requests/>

You must be aware that "each call within the batch is counted separately for
the purposes of calculating API call limits and resource limits."
See L<https://developers.facebook.com/docs/reference/ads-api/api-rate-limiting/>.

=item * is_beta

Weather to use beta tier. See the official documentation for details.
L<https://developers.facebook.com/support/beta-tier/>.

=item * json

JSON object that handles request parameters and API response. Default is
equivalent to JSON->new->utf8.

=item * use_appsecret_proof

Whether to use appsecret_proof parameter or not. Default is 0.
Long-desired official document is now provided at
L<https://developers.facebook.com/docs/graph-api/securing-requests/>

You must specify access_token and application secret to utilize this.

=back