| 1 |
NAME |
| 2 |
WWW::Facebook::API - Facebook API implementation |
| 3 |
|
| 4 |
VERSION |
| 5 |
This document and others distributed with this module describe |
| 6 |
WWW::Facebook::API version 0.4.18 |
| 7 |
|
| 8 |
SYNOPSIS |
| 9 |
use WWW::Facebook::API; |
| 10 |
|
| 11 |
# @ENV{qw/WFA_API_KEY WFA_SECRET WFA_DESKTOP/} are the initial values, |
| 12 |
# so use those if you only have one app and don't want to pass in values |
| 13 |
# to constructor |
| 14 |
my $client = WWW::Facebook::API->new( |
| 15 |
desktop => 0, |
| 16 |
api_key => 'your api key', |
| 17 |
secret => 'your secret key', |
| 18 |
); |
| 19 |
|
| 20 |
# Change API key and secret |
| 21 |
print "Enter your public API key: "; |
| 22 |
chomp( my $val = <STDIN> ); |
| 23 |
$client->api_key($val); |
| 24 |
print "Enter your API secret: "; |
| 25 |
chomp($val = <STDIN> ); |
| 26 |
$client->secret($val); |
| 27 |
|
| 28 |
# not needed if web app (see $client->canvas->get_fb_params) |
| 29 |
$client->auth->get_session( $token ); |
| 30 |
|
| 31 |
use Data::Dumper; |
| 32 |
my $friends_perl = $client->friends->get; |
| 33 |
print Dumper $friends_perl; |
| 34 |
|
| 35 |
my $notifications_perl = $client->notifications->get; |
| 36 |
print Dumper $notifications_perl; |
| 37 |
|
| 38 |
# Current user's quotes |
| 39 |
my $quotes_perl = $client->users->get_info( |
| 40 |
uids => $friends_perl, |
| 41 |
fields => ['quotes'] |
| 42 |
); |
| 43 |
print Dumper $quotes_perl; |
| 44 |
|
| 45 |
$client->auth->logout; |
| 46 |
|
| 47 |
DESCRIPTION |
| 48 |
A Perl implementation of the Facebook API, working off of the canonical |
| 49 |
Java and PHP implementations. By default it uses JSON::Any to parse the |
| 50 |
response returned by Facebook's server. There is an option to return the |
| 51 |
raw response in either XML or JSON (See the "parse" method below). As |
| 52 |
the synopsis states, the following environment variables are used to set |
| 53 |
the defaults for new instances: |
| 54 |
|
| 55 |
WFA_API_KEY |
| 56 |
WFA_SECRET |
| 57 |
WFA_SESSION_KEY |
| 58 |
WFA_DESKTOP |
| 59 |
|
| 60 |
Additionally, for each instance that is created, the following |
| 61 |
environment variables are used if no values are set: |
| 62 |
|
| 63 |
WFA_API_KEY_APP_PATH |
| 64 |
WFA_SECRET_APP_PATH |
| 65 |
WFA_SESSION_KEY_APP_PATH |
| 66 |
WFA_DESKTOP_APP_PATH |
| 67 |
|
| 68 |
Where "APP_PATH" is replaced by whatever $client->app_path returns, with |
| 69 |
all non-alphanumeric characters replaced with an underscore and all |
| 70 |
characters upcased (e.g., foo-bar-baz becomes FOO_BAR_BAZ). |
| 71 |
|
| 72 |
SUBROUTINES/METHODS |
| 73 |
new( %params ) |
| 74 |
Returns a new instance of this class. You are able to pass in any of |
| 75 |
the attribute method names in WWW::Facebook::API to set its value: |
| 76 |
|
| 77 |
my $client = WWW::Facebook::API->new( |
| 78 |
parse => 1, |
| 79 |
format => 'JSON', |
| 80 |
secret => 'application_secret_key', |
| 81 |
api_key => 'application_key', |
| 82 |
session_key => 'session_key', |
| 83 |
session_expires => 'session_expires', |
| 84 |
session_uid => 'session_uid', |
| 85 |
desktop => 1, |
| 86 |
api_version => '1.0', |
| 87 |
callback => 'callback_url', |
| 88 |
next => 'next', |
| 89 |
popup => 'popup', |
| 90 |
skipcookie => 'skip_cookie', |
| 91 |
throw_errors => 1, |
| 92 |
); |
| 93 |
$copy = $client->new; |
| 94 |
|
| 95 |
NAMESPACE METHODS |
| 96 |
All method names from the Facebook API are lower_cased instead of |
| 97 |
CamelCase. |
| 98 |
|
| 99 |
admin |
| 100 |
admin namespace of the API (See WWW::Facebook::API::Admin). |
| 101 |
|
| 102 |
application |
| 103 |
application namespace of the API (See |
| 104 |
WWW::Facebook::API::Application). |
| 105 |
|
| 106 |
auth |
| 107 |
For desktop apps, these are synonymous: |
| 108 |
|
| 109 |
$client->auth->get_session( $client->auth->create_token ); |
| 110 |
$client->auth->get_session; |
| 111 |
|
| 112 |
And that's all you really have to do (but see |
| 113 |
WWW::Facebook::API::Auth for details about opening a browser on *nix |
| 114 |
for Desktop apps). "get_session" automatically sets "session_uid", |
| 115 |
"session_key", and "session_expires" for $client. It returns |
| 116 |
nothing. |
| 117 |
|
| 118 |
If the desktop attribute is set to false the $token must be the |
| 119 |
auth_token returned from Facebook to your web app for that user: |
| 120 |
|
| 121 |
if ( $q->param('auth_token') ) { |
| 122 |
$client->auth->get_session( $q->param('auth_token') ); |
| 123 |
} |
| 124 |
|
| 125 |
"get_session" automatically sets "session_uid", "session_key", and |
| 126 |
"session_expires" for $client. It returns nothing. |
| 127 |
|
| 128 |
See WWW::Facebook::API::Auth for details. |
| 129 |
|
| 130 |
canvas |
| 131 |
Work with the canvas. See WWW::Facebook::API::Canvas. |
| 132 |
|
| 133 |
$response = $client->canvas->get_user( $q ) |
| 134 |
$response = $client->canvas->get_fb_params( $q ) |
| 135 |
$response = $client->canvas->get_non_fb_params( $q ) |
| 136 |
$response = $client->canvas->validate_sig( $q ) |
| 137 |
$response = $client->canvas->in_fb_canvas( $q ) |
| 138 |
$response = $client->canvas->in_frame( $q ) |
| 139 |
|
| 140 |
comments |
| 141 |
comments namespace of the API (See WWW::Facebook::API::Comments). |
| 142 |
|
| 143 |
connect |
| 144 |
connect namespace of the API (See WWW::Facebook::API::Connect). |
| 145 |
|
| 146 |
data |
| 147 |
data namespace of the API (See WWW::Facebook::API::Data). All method |
| 148 |
names from the Facebook API are lower_cased instead of CamelCase: |
| 149 |
|
| 150 |
$response = $client->data->set_cookie( uid => 23, qw/name foo value bar/); |
| 151 |
$cookies = $client->data->get_cookies( |
| 152 |
uid => 4534, |
| 153 |
name => 'foo', |
| 154 |
); |
| 155 |
|
| 156 |
events |
| 157 |
events namespace of the API (See WWW::Facebook::API::Events). All |
| 158 |
method names from the Facebook API are lower_cased instead of |
| 159 |
CamelCase: |
| 160 |
|
| 161 |
$response = $client->events->get( |
| 162 |
uid => 'uid', |
| 163 |
eids => [@eids], |
| 164 |
start_time => 'utc', |
| 165 |
end_time => 'utc', |
| 166 |
rsvp_status => 'attending|unsure|declined|not_replied', |
| 167 |
); |
| 168 |
$response = $client->events->get_members( eid => 233 ); |
| 169 |
|
| 170 |
fbml |
| 171 |
fbml namespace of the API (See WWW::Facebook::API::FBML). All method |
| 172 |
names from the Facebook API are lower_cased instead of CamelCase: |
| 173 |
|
| 174 |
$response = $client->fbml->set_ref_handle( handle => '', fbml => ''); |
| 175 |
$response = $client->fbml->refresh_img_src( url => ''); |
| 176 |
$response = $client->fbml->refresh_ref_url( url => ''); |
| 177 |
|
| 178 |
feed |
| 179 |
feed namespace of the API (See WWW::Facebook::API::Feed). All method |
| 180 |
names from the Facebook API are lower_cased instead of CamelCase: |
| 181 |
|
| 182 |
$response |
| 183 |
= $client->feed->publish_story_to_user( |
| 184 |
title => 'title', |
| 185 |
body => 'markup', |
| 186 |
... |
| 187 |
); |
| 188 |
$response |
| 189 |
= $client->feed->publish_action_of_user( |
| 190 |
title => 'title', |
| 191 |
body => 'markup', |
| 192 |
... |
| 193 |
); |
| 194 |
$response |
| 195 |
= $client->feed->publish_templatized_action( |
| 196 |
actor_id => 'title', |
| 197 |
title_template => 'markup', |
| 198 |
... |
| 199 |
); |
| 200 |
|
| 201 |
fql fql namespace of the API (See WWW::Facebook::API::FQL): |
| 202 |
|
| 203 |
$response = $client->fql->query( query => 'FQL query' ); |
| 204 |
|
| 205 |
friends |
| 206 |
friends namespace of the API (See WWW::Facebook::API::Friends). All |
| 207 |
method names from the Facebook API are lower_cased instead of |
| 208 |
CamelCase: |
| 209 |
|
| 210 |
$response = $client->friends->get; |
| 211 |
$response = $client->friends->get_app_users; |
| 212 |
$response |
| 213 |
= $client->friends->are_friends( uids1 => [1,5,8], uids2 => [2,3,4] ); |
| 214 |
$response = $client->friends->get_lists; |
| 215 |
|
| 216 |
groups |
| 217 |
groups namespace of the API (See WWW::Facebook::API::Groups). All |
| 218 |
method names from the Facebook API are lower_cased instead of |
| 219 |
CamelCase: |
| 220 |
|
| 221 |
$response = $client->groups->get( uid => 234324, gids => [2423,334] ); |
| 222 |
$response = $client->groups->get_members( gid => 32 ); |
| 223 |
|
| 224 |
intl |
| 225 |
intl namespace of the API (See WWW::Facebook::API::Intl). |
| 226 |
|
| 227 |
links |
| 228 |
links namespace of the API (See WWW::Facebook::API::Links). |
| 229 |
|
| 230 |
livemesssage |
| 231 |
liveMesssage namespace of the API (See |
| 232 |
WWW::Facebook::API::LiveMesssage). |
| 233 |
|
| 234 |
message |
| 235 |
message namespace of the API (See WWW::Facebook::API::Message). |
| 236 |
|
| 237 |
notes |
| 238 |
notes namespace of the API (See WWW::Facebook::API::Notes). |
| 239 |
|
| 240 |
notifications |
| 241 |
notifications namespace of the API (See |
| 242 |
WWW::Facebook::API::Notifications). All method names from the |
| 243 |
Facebook API are lower_cased instead of CamelCase: |
| 244 |
|
| 245 |
$response = $client->notifications->get; |
| 246 |
$response = $client->notifications->send( |
| 247 |
to_ids => [ 1, 3 ], |
| 248 |
notification => 'FBML notification markup', |
| 249 |
); |
| 250 |
$response = $client->notifications->send_email( |
| 251 |
recipients => [1, 2343, 445], |
| 252 |
subject => 'subject', |
| 253 |
text => 'text version of email body', |
| 254 |
fbml => 'fbml version of email body', |
| 255 |
); |
| 256 |
|
| 257 |
pages |
| 258 |
pages namespace of the API (See WWW::Facebook::API::Pages). All |
| 259 |
method names from the Facebook API are lower_cased instead of |
| 260 |
CamelCase: |
| 261 |
|
| 262 |
$response = $client->pages->get_info( |
| 263 |
page_ids => [@pages], |
| 264 |
fields => [@fields], |
| 265 |
uid => 'user', |
| 266 |
type => 'page type', |
| 267 |
); |
| 268 |
$page_added_app = $client->pages->is_app_added( page_id => 'page' ); |
| 269 |
$is_admin = $client->pages->is_admin( page_id => 'page' ); |
| 270 |
$is_fan = $client->pages->is_fan( page_id => 'page', uid => 'uid' ) |
| 271 |
|
| 272 |
permissions |
| 273 |
permissions namespace of the API (See |
| 274 |
WWW::Facebook::API::Permissions). |
| 275 |
|
| 276 |
photos |
| 277 |
photos namespace of the API (See WWW::Facebook::API::Photos). All |
| 278 |
method names from the Facebook API are lower_cased instead of |
| 279 |
CamelCase: |
| 280 |
|
| 281 |
$response = $client->photos->add_tag( |
| 282 |
pid => 2, |
| 283 |
tag_uid => 3, |
| 284 |
tag_text => "me", |
| 285 |
x => 5, |
| 286 |
y => 6 |
| 287 |
); |
| 288 |
$response = $client->photos->create_album( |
| 289 |
name => 'fun in the sun', |
| 290 |
location => 'California', |
| 291 |
description => "Summer '07", |
| 292 |
); |
| 293 |
$response = $client->photos->get( aid => 2, pids => [4,7,8] ); |
| 294 |
$response = $client->photos->get_albums( uid => 1, pids => [3,5] ); |
| 295 |
$response = $client->photos->get_tags( pids => [4,5] ); |
| 296 |
$response = $client->photos->upload( |
| 297 |
aid => 5, |
| 298 |
caption => 'beach', |
| 299 |
data => 'raw data', |
| 300 |
); |
| 301 |
|
| 302 |
profile |
| 303 |
profile namespace of the API (See WWW::Facebook::API::Profile). All |
| 304 |
method names from the Facebook API are lower_cased instead of |
| 305 |
CamelCase: |
| 306 |
|
| 307 |
$response = $client->profile->get_fbml( uid => 3 ); |
| 308 |
$response = $client->profile->set_fbml( uid => 5, |
| 309 |
profile => 'markup', |
| 310 |
profile_action => 'markup', |
| 311 |
mobile_profile => 'markup', |
| 312 |
); |
| 313 |
|
| 314 |
sms sms namespace of the API (See WWW::Facebook::API::SMS). |
| 315 |
|
| 316 |
status |
| 317 |
status namespace of the API (See WWW::Facebook::API::Status). |
| 318 |
|
| 319 |
stream |
| 320 |
stream namespace of the API (See WWW::Facebook::API::Stream). |
| 321 |
|
| 322 |
users |
| 323 |
users namespace of the API (See WWW::Facebook::API::Users). All |
| 324 |
method names from the Facebook API are lower_cased instead of |
| 325 |
CamelCase: |
| 326 |
|
| 327 |
$response = $client->users->get_info( |
| 328 |
uids => 2343, |
| 329 |
fields => [ qw/about_me quotes/ ] |
| 330 |
); |
| 331 |
$uid = $client->users->get_logged_in_user; |
| 332 |
$response = $client->users->has_app_permission( |
| 333 |
ext_perm => 'status_update|photo_upload' |
| 334 |
); |
| 335 |
$app_added = $client->users->is_app_user; |
| 336 |
$response = $client->users->set_status( |
| 337 |
status => 'status message', |
| 338 |
clear => 1|0, |
| 339 |
); |
| 340 |
|
| 341 |
video |
| 342 |
video namespace of the API (See WWW::Facebook::API::Video). |
| 343 |
|
| 344 |
ATTRIBUTE METHODS |
| 345 |
These are methods to get/set the object's attributes. |
| 346 |
|
| 347 |
api_key( $new_api_key ) |
| 348 |
The developer's API key. If $ENV{'WFA_API_KEY'} is set, all |
| 349 |
instances will be initialized with its value. See the Facebook API |
| 350 |
documentation for more information. |
| 351 |
|
| 352 |
api_version( $new_version ) |
| 353 |
Which version to use (default is "1.0", which is the latest one |
| 354 |
supported currently). Corresponds to the argument "v" that is passed |
| 355 |
in to methods as a parameter. |
| 356 |
|
| 357 |
app_id() |
| 358 |
The application id where your Facebook app is described, e.g.: |
| 359 |
|
| 360 |
http://www.facebook.com/apps/application.php?id=THIS_NUMBER |
| 361 |
|
| 362 |
Remember, "WWW::Facebook::API" is not that clairvoyant: You must |
| 363 |
first set this number (when calling "new()") in order to use it. |
| 364 |
|
| 365 |
app_path() |
| 366 |
If using the Facebook canvas, the path to your application. For |
| 367 |
example if your application is at http://apps.facebook.com/example/ |
| 368 |
this should be "example". |
| 369 |
|
| 370 |
apps_uri() |
| 371 |
The apps uri for Facebook apps. The default is |
| 372 |
http://apps.facebook.com/. |
| 373 |
|
| 374 |
callback( $new_default_callback ) |
| 375 |
The callback URL for your application. See the Facebook API |
| 376 |
documentation. Just a convenient place holder for the value. |
| 377 |
|
| 378 |
call_success( $is_success, $error_message ) |
| 379 |
Takes in two values, the first setting the object's |
| 380 |
last_call_success attribute, and the second setting the object's |
| 381 |
last_error attribute. Returns an array reference containing the |
| 382 |
last_call_success and last_error values, in that order: |
| 383 |
|
| 384 |
my $response = $client->call_success( 1, undef ); |
| 385 |
if ( $response->[0] == 1 ) { |
| 386 |
print 'Last call successful'; |
| 387 |
} |
| 388 |
if ( not defined $response->[1] ) { |
| 389 |
print 'Error message is undefined'; |
| 390 |
} |
| 391 |
|
| 392 |
$client->call_success( 0,'2: The service is not available at this time.'); |
| 393 |
|
| 394 |
$response = $client->call_success; |
| 395 |
if ( not $response->[0] ) { |
| 396 |
print 'Last call unsuccessful'; |
| 397 |
} |
| 398 |
if ( not defined $response->[1] ) { |
| 399 |
print "Error $response->[1]"; |
| 400 |
} |
| 401 |
|
| 402 |
The "call" method calls this method, and shouldn't need to be called |
| 403 |
to set anything, just to get the value later if "throw_errors" is |
| 404 |
false. |
| 405 |
|
| 406 |
config($filename) |
| 407 |
Used when instantiating a new object to set the environment |
| 408 |
variables. The file has a simple, BASH-style format: |
| 409 |
|
| 410 |
WFA_API_KEY_MYAPP=383378efa485934bc |
| 411 |
WFA_SECRET_MYAPP=234234ac902f340923 |
| 412 |
WFA_SESSION_KEY_MYAPP=34589349abce989d |
| 413 |
WFA_DESKTOP_MYAPP=1 |
| 414 |
|
| 415 |
If the file is found, and the environment variables are already set, |
| 416 |
then the variables will not be changed. |
| 417 |
|
| 418 |
debug(0|1) |
| 419 |
A boolean set to either true or false, determining if debugging |
| 420 |
messages should be carped for REST calls. Defaults to 0. |
| 421 |
|
| 422 |
desktop(0|1) |
| 423 |
A boolean signifying if the client is being used for a desktop |
| 424 |
application. If $ENV{'WFA_DESKTOP'} is set, all instances will be |
| 425 |
initialized with its value. Defaults to 0 otherwise. See the |
| 426 |
Facebook API documentation for more information. |
| 427 |
|
| 428 |
format('JSON'|'XML') |
| 429 |
The default format to use if none is supplied with an API method |
| 430 |
call. Currently available options are XML and JSON. Defaults to |
| 431 |
JSON. |
| 432 |
|
| 433 |
last_call_success(1|0) |
| 434 |
A boolean set to true or false, to show whether the last call was |
| 435 |
succesful or not. Called by "call_success". Defaults to 1. |
| 436 |
|
| 437 |
last_error( $error_message ) |
| 438 |
A string holding the error message of the last failed call to the |
| 439 |
REST server. Called by "call_success". Defaults to undef. |
| 440 |
|
| 441 |
next( $new_default_next_url ) |
| 442 |
See the Facebook API documentation's Authentication Guide. Just a |
| 443 |
convenient place holder for the value. |
| 444 |
|
| 445 |
parse(1|0) |
| 446 |
Defaults to 1. If set to true, the response returned by each method |
| 447 |
call will be a Perl structure (see each method for the structure it |
| 448 |
will return). If it is set to 0, the response string from the server |
| 449 |
will be returned. (The response string is unescaped if the 'desktop' |
| 450 |
attribute is false). |
| 451 |
|
| 452 |
popup( $popup ) |
| 453 |
See the Facebook API documentation's Authentication Guide. Just a |
| 454 |
convenient place holder for the value. |
| 455 |
|
| 456 |
query( $query ) |
| 457 |
Stores the current query object to use (either CGI or |
| 458 |
Apache::Request) but really anything that implements the "param()" |
| 459 |
method can be used. N.B. When using "require_*" methods below, |
| 460 |
Apache::Request will croak because it does not implement a redirect |
| 461 |
method. |
| 462 |
|
| 463 |
secret( $new_secret_key ) |
| 464 |
For a desktop application, this is the secret that is used for |
| 465 |
calling "auth->create_token" and "auth->get_session". For a web |
| 466 |
application, secret is used for all calls to the API. If |
| 467 |
$ENV{'WFA_SECRET'} is set, all instances will be initialized with |
| 468 |
its value. See the Facebook API documentation under Authentication |
| 469 |
for more information. |
| 470 |
|
| 471 |
server_uri( $new_server_uri ) |
| 472 |
The server uri to access the Facebook REST server. Default is |
| 473 |
'http://api.facebook.com/restserver.php'. Used to make calls to the |
| 474 |
Facebook server, and useful for testing. See the Facebook API |
| 475 |
documentation. |
| 476 |
|
| 477 |
session_expires( $new_expires ) |
| 478 |
The session expire timestamp for the client's user. Automatically |
| 479 |
set when "$client->auth->get_session" is called. See the Facebook |
| 480 |
API documentation. |
| 481 |
|
| 482 |
session_key( $new_key ) |
| 483 |
The session key for the client's user. Automatically set when |
| 484 |
"$client->auth->get_session" is called. See the Facebook API |
| 485 |
documentation. |
| 486 |
|
| 487 |
session_uid( $new_uid ) |
| 488 |
The session's uid for the client's user. Automatically set when |
| 489 |
"$client->auth->get_session" is called. See the Facebook API |
| 490 |
documentation. |
| 491 |
|
| 492 |
skipcookie(0|1) |
| 493 |
See the Facebook API documentation's Authentication Guide. Just a |
| 494 |
convenient place holder for the value. |
| 495 |
|
| 496 |
throw_errors(0|1) |
| 497 |
A boolean set to either true of false, signifying whether or not to |
| 498 |
"confess" when an error is returned from the REST server. |
| 499 |
|
| 500 |
ua The LWP::UserAgent agent used to communicate with the REST server. |
| 501 |
The agent_alias is initially set to "Perl-WWW-Facebook-API/0.4.18". |
| 502 |
|
| 503 |
PUBLIC METHODS |
| 504 |
call( $method, %args ) |
| 505 |
The method which other submodules within WWW::Facebook::API use to |
| 506 |
call the Facebook REST interface. It takes in a string signifying |
| 507 |
the method to be called (e.g., 'auth.getSession'), and key/value |
| 508 |
pairs for the parameters to use: $client->call( 'auth.getSession', |
| 509 |
auth_token => 'b3324235e' ); |
| 510 |
|
| 511 |
For all calls, if " parse " is set to true and an empty hash/array |
| 512 |
reference is returned from facebook, nothing will be returned |
| 513 |
instead of the empty hash/array reference. |
| 514 |
|
| 515 |
generate_sig( params => $params_hashref, secret => $secret ) |
| 516 |
Generates a sig when given a parameters hash reference and a secret |
| 517 |
key. |
| 518 |
|
| 519 |
get_add_url( %params ) |
| 520 |
Returns the URL to add your application with the parameters (that |
| 521 |
are given) included. Note that the API key and the API version |
| 522 |
parameters are also included automatically. If the "next" parameter |
| 523 |
is passed in, it's string-escaped. Used for platform applications: |
| 524 |
|
| 525 |
$response = $client->get_add_url( next => 'http://my.website.com' ); |
| 526 |
|
| 527 |
# prints http://www.facebook.com/app.php?api_key=key&v=1.0 |
| 528 |
# &next=http%3A%2F%2Fmy.website.com |
| 529 |
print $response; |
| 530 |
|
| 531 |
get_app_url |
| 532 |
Returns the URL to your application, if using the Facebook canvas. |
| 533 |
Uses <$client->app_path>, which you have to set yourself (See |
| 534 |
<app_path> below). |
| 535 |
|
| 536 |
get_facebook_url( $subdomain ) |
| 537 |
Returns the URL to Facebook. You can specifiy a specific network as |
| 538 |
a parameter: |
| 539 |
|
| 540 |
$response = $client->get_facebook_url( 'apps' ); |
| 541 |
print $response; # prints http://apps.facebook.com |
| 542 |
|
| 543 |
get_infinite_session_url() |
| 544 |
Returns the URL for the user to generate an infinite session for |
| 545 |
your application: |
| 546 |
|
| 547 |
$response = $client->get_infinite_session_url; |
| 548 |
|
| 549 |
# prints http://www.facebook.com/codegen.php?api_key=key&v=1.0 |
| 550 |
print $response; |
| 551 |
|
| 552 |
From what I've seen, the session keys that Facebook returns don't |
| 553 |
expire automatically, so as long as you don't call |
| 554 |
$client->auth->logout, you shouldn't even need to worry about this. |
| 555 |
|
| 556 |
get_login_url( %params ) |
| 557 |
Returns the URL to login to your application with the parameters |
| 558 |
(that are defined) included. If the "next" parameter is passed in, |
| 559 |
it's string-escaped: |
| 560 |
|
| 561 |
$response = $client->get_login_url( next => 'http://my.website.com' ); |
| 562 |
|
| 563 |
# prints http://www.facebook.com/login.php?api_key=key&v=1.0 |
| 564 |
# &next=http%3A%2F%2Fmy.website.com |
| 565 |
print $response; |
| 566 |
|
| 567 |
get_url( $type, @args ) |
| 568 |
Called by all the above "get_*_url" methods above. $type can be |
| 569 |
'login', 'app', 'add', 'facebook', 'infinite_session', or 'custom'. |
| 570 |
@args contains the query parameters for the the cases when $type is |
| 571 |
not 'app' or 'facebook'. In the case of 'custom', the first item in |
| 572 |
@args is the url path relative to the facebook website. All of the |
| 573 |
"get_*_url" methods correspond to the ones in the official PHP |
| 574 |
client. |
| 575 |
|
| 576 |
log_string($params_hashref, $response) |
| 577 |
Pass in the params and the response from a call, and it will make a |
| 578 |
formatted string out of it showing the parameters used, and the |
| 579 |
response received. |
| 580 |
|
| 581 |
redirect( $url, $query_object ) |
| 582 |
Called by "require()" to redirect the user either within the canvas |
| 583 |
or without. If no <$query_object> is defined, then whatever is in |
| 584 |
"$client->query" will be used. (See WWW::Facebook::API::Canvas) If |
| 585 |
no redirect is required, nothing is returned. That is the only case |
| 586 |
when there is no return value. If a redirect is required, there are |
| 587 |
two cases that are covered: |
| 588 |
|
| 589 |
user not logged in |
| 590 |
If there isn't a user logged in to Facebook's system, then a |
| 591 |
redirect to the Facebook login page is printed to STDOUT with a |
| 592 |
next parameter to the appropriate page. The redirect is called |
| 593 |
with the the CGI module that comes standard with perl. The |
| 594 |
return value in this case is 1. |
| 595 |
|
| 596 |
user logged in |
| 597 |
If the user is logged in to Facebook, and a redirect is |
| 598 |
required, the necessary FBML is returned: "<fb:redirect |
| 599 |
url="WHATEVER">". So the return value is the FBML, which you can |
| 600 |
then print to STDOUT. |
| 601 |
|
| 602 |
require_add( $query ) |
| 603 |
Redirects the user to what "get_add_url()" returns. See "require()" |
| 604 |
below for the $query parameter. |
| 605 |
|
| 606 |
require_frame( $query ) |
| 607 |
Redirects the user to what "get_login_url( canvas =" '1' )> returns. |
| 608 |
See "require()" below for the $query parameter. |
| 609 |
|
| 610 |
require_login( $query ) |
| 611 |
Redirects the user to what "get_login_url()" returns. See |
| 612 |
"require()" below for the $query parameter. |
| 613 |
|
| 614 |
require( $what, $query ) |
| 615 |
The official PHP client has "require_*" methods that take no |
| 616 |
arguments. Logically, you better know what you want to require when |
| 617 |
you call each of them, so this API consolidates them into one |
| 618 |
method. The valid values for $what are 'add', 'frame', and 'login'. |
| 619 |
$query is the query object to use (most likely CGI). If $query is |
| 620 |
undefined, the value of " $client-"query >> is used. |
| 621 |
|
| 622 |
session( uid => $uid, key => $session_key, expires => $session_expires ) |
| 623 |
Sets the "user", "session_key", and "session_expires" all at once. |
| 624 |
|
| 625 |
unescape_string($escaped_string) |
| 626 |
Returns its parameter with all the escape sequences unescaped. If |
| 627 |
you're using a web app, this is done automatically to the response. |
| 628 |
|
| 629 |
verify_sig( sig => $expected_sig, params => $params_hashref ) |
| 630 |
Checks the signature for a given set of parameters against an |
| 631 |
expected value. |
| 632 |
|
| 633 |
PRIVATE METHODS |
| 634 |
_add_url_params( %params ) |
| 635 |
Called by both "get_login_url" and "get_add_url" to process any of |
| 636 |
their parameters. Prepends the api_key and the version number as |
| 637 |
parameters and returns the parameter string. |
| 638 |
|
| 639 |
_check_values_of($params_hashref) |
| 640 |
Makes sure all the values of the $params_hashref that need to be set |
| 641 |
are set. Uses the defaults for those values that are needed and not |
| 642 |
supplied. |
| 643 |
|
| 644 |
_format_and_check_params( $method, %args ) |
| 645 |
Format method parameters (given in %args) according to Facebook API |
| 646 |
specification. Returns a list of items: A hash reference of the |
| 647 |
newly formatted params (based on %params) and the raw data (and |
| 648 |
filename, if passed in) if the call is a photo or video upload: |
| 649 |
|
| 650 |
($params, $raw_data, $filename) = $self->_format_and_check_params( $method, %args ); |
| 651 |
|
| 652 |
_has_error_response( $response ) |
| 653 |
Determines if the response is an error, and logs it appropriately. |
| 654 |
Returns true if response is an error, false otherwise. |
| 655 |
|
| 656 |
is_empty_response( $response ) |
| 657 |
Determines if the response is an empty hash or array reference. |
| 658 |
Returns true if the response is empty, false otherwise. |
| 659 |
|
| 660 |
_post_request( $params_hashref, $sig, $raw_data, $filename ) |
| 661 |
Used by "call" to post the request to the REST server and return the |
| 662 |
response. $raw_data and $filename are used when uploading a photo or |
| 663 |
video to Facebook. |
| 664 |
|
| 665 |
_parse($string) |
| 666 |
Parses the response from a call to the Facebook server to make it a |
| 667 |
Perl data structure, and returns the result. |
| 668 |
|
| 669 |
_parser() |
| 670 |
Returns a new instance of JSON::Any. |
| 671 |
|
| 672 |
_reformat_response( $params, $response ) |
| 673 |
Reformats the response according to whether the app is a desktop |
| 674 |
app, if the response should be parsed (i.e., changed to a Perlish |
| 675 |
structure), if the response is empty, etc. Returns the reformatted |
| 676 |
response. |
| 677 |
|
| 678 |
DIAGNOSTICS |
| 679 |
"Unable to load JSON module for parsing: %s" |
| 680 |
JSON::Any was not able to load one of the JSON modules it uses to |
| 681 |
parse JSON. Please make sure you have one (of the several) JSON |
| 682 |
modules it can use installed. |
| 683 |
|
| 684 |
"Error during REST call: %s" |
| 685 |
This means that there's most likely an error in the server you are |
| 686 |
using to communicate to the Facebook REST server. Look at the |
| 687 |
traceback to determine why an error was thrown. Double-check that |
| 688 |
"server_uri" is set to the right location. |
| 689 |
|
| 690 |
"Cannot create namespace %s: %s" |
| 691 |
Cannot create the needed subclass method. Contact the developer to |
| 692 |
report. |
| 693 |
|
| 694 |
"Cannot create attribute %s: %s" |
| 695 |
Cannot create the needed attribute method. Contact the developer to |
| 696 |
report. |
| 697 |
|
| 698 |
"<_format_and_check_params must be called in list context!"> |
| 699 |
You're using a private method call and you're not calling it in list |
| 700 |
context. It returns a list of items, all of which should be |
| 701 |
interesting to you. |
| 702 |
|
| 703 |
"Cannot open %s" |
| 704 |
Cannot open the configuration file. Make sure the filename is |
| 705 |
correct and that the program has the appropriate permissions. |
| 706 |
|
| 707 |
"Cannot close %s" |
| 708 |
Cannot close the configuration file. Make sure the filename is |
| 709 |
correct and that the program has the appropriate permissions. |
| 710 |
|
| 711 |
FAQ |
| 712 |
Id numbers returned by Facebook are being rounded. What is the problem? |
| 713 |
The JSON module that is installed on your system is converting the |
| 714 |
numbers to Perl and is losing precision in the process. Make sure |
| 715 |
you have the latest JSON::XS module installed or JSON::DWIW (any |
| 716 |
recent version of either should work). |
| 717 |
|
| 718 |
How do I run the examples in the examples directory? |
| 719 |
There are two types of examples in the examples directory, |
| 720 |
desktop-based and web-based. With desktop-based, the api key and |
| 721 |
secret key are prompted for on STDIN, and then the user's browser is |
| 722 |
opened and directed to the Facebook log in page. Currently, the |
| 723 |
desktop-based examples pause for 20 seconds to allow for the user to |
| 724 |
enter in their credentials. |
| 725 |
|
| 726 |
With web-based, you have to pass in the api key, secret key, and app |
| 727 |
path to the constructor, and then place the script at the callback |
| 728 |
url you specified in the Facebook setup for your application. For |
| 729 |
instance, when using the web-based example, you might have the |
| 730 |
following callback url (note the trailing slash): |
| 731 |
|
| 732 |
http://www.example.com/facebook-canvas-json/ |
| 733 |
|
| 734 |
You have to make sure the required Perl modules are in the @INC path |
| 735 |
for the web server process, otherwise there will be a 500 Internal |
| 736 |
Server error. The easiest way to do that is to put the following at |
| 737 |
the top of the example script (as long as "path-to-perl5-libs" is |
| 738 |
readable by the web server process): |
| 739 |
|
| 740 |
use lib "path-to-perl5-libs"; |
| 741 |
|
| 742 |
I'm getting the "Multiple values for %s" error from WFA::Canvas. Help? |
| 743 |
This usually means that your forms are using GET rather than POST to |
| 744 |
Facebook URLs. Change your forms to use POST and the problem should |
| 745 |
be resolved. (See RT#31620 and RT#31944 for more information). |
| 746 |
|
| 747 |
CONFIGURATION AND ENVIRONMENT |
| 748 |
WWW::Facebook::API requires no configuration files or environment |
| 749 |
variables. |
| 750 |
|
| 751 |
DEPENDENCIES |
| 752 |
version Crypt::SSLeay Digest::MD5 JSON::Any Time::HiRes LWP::UserAgent |
| 753 |
|
| 754 |
INCOMPATIBILITIES |
| 755 |
None. |
| 756 |
|
| 757 |
BUGS AND LIMITATIONS |
| 758 |
No bugs have been reported. |
| 759 |
|
| 760 |
Please report any bugs or feature requests to |
| 761 |
"[email protected]", or through the web interface at |
| 762 |
<http://rt.cpan.org>. |
| 763 |
|
| 764 |
SOURCE REPOSITORY |
| 765 |
http://github.com/unobe/perl-wfa/tree/master |
| 766 |
|
| 767 |
TESTING |
| 768 |
There are some live tests included, but they are only run if the |
| 769 |
following environment variables are set: WFA_API_KEY_TEST |
| 770 |
WFA_SECRET_TEST WFA_SESSION_KEY_TEST |
| 771 |
|
| 772 |
Additionally, if your app is a desktop one, you must set |
| 773 |
"WFA_DESKTOP_TEST". Also, the session key must be valid for the API key |
| 774 |
being used. |
| 775 |
|
| 776 |
To enable POD coverage and POD formattings tests, set "PERL_TEST_POD" to |
| 777 |
true. To enable Perl::Critic tests, set "_PERL_TEST_CRITIC" to true. |
| 778 |
|
| 779 |
AUTHOR |
| 780 |
David Romano "<[email protected]>" |
| 781 |
|
| 782 |
CONTRIBUTORS |
| 783 |
Anthony Bouvier "none" |
| 784 |
|
| 785 |
Clayton Scott "http://www.matrix.ca" |
| 786 |
|
| 787 |
David Leadbeater "http://dgl.cx" |
| 788 |
|
| 789 |
Derek Del Conte "[email protected]" |
| 790 |
|
| 791 |
Gisle Aas "none" |
| 792 |
|
| 793 |
J. Shirley "<[email protected]>" |
| 794 |
|
| 795 |
Jim Spath "<[email protected]>" |
| 796 |
|
| 797 |
Kevin Riggle "none" |
| 798 |
|
| 799 |
Larry Mak "none" |
| 800 |
|
| 801 |
Louis-Philippe "none" |
| 802 |
|
| 803 |
Matt Sickler "<[email protected]>" |
| 804 |
|
| 805 |
Nick Gerakines "<[email protected]>" |
| 806 |
|
| 807 |
Olaf Alders "<[email protected]>" |
| 808 |
|
| 809 |
Patrick Michael Kane "<[email protected]>" |
| 810 |
|
| 811 |
Ryan D Johnson "[email protected]" |
| 812 |
|
| 813 |
Sean O'Rourke "<[email protected]>" |
| 814 |
|
| 815 |
Shawn Van Ittersum "none" |
| 816 |
|
| 817 |
Simon Cavalletto "<[email protected]>" |
| 818 |
|
| 819 |
Skyler Clark "none" |
| 820 |
|
| 821 |
Thomas Sibley "<[email protected]>" |
| 822 |
|
| 823 |
LICENSE AND COPYRIGHT |
| 824 |
Copyright (c) 2007-2010, David Romano "<[email protected]>". All rights |
| 825 |
reserved. |
| 826 |
|
| 827 |
This module is free software; you can redistribute it and/or modify it |
| 828 |
under the same terms as Perl itself. See perlartistic. |
| 829 |
|
| 830 |
DISCLAIMER OF WARRANTY |
| 831 |
BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY |
| 832 |
FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN |
| 833 |
OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES |
| 834 |
PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER |
| 835 |
EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED |
| 836 |
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE |
| 837 |
ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH |
| 838 |
YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL |
| 839 |
NECESSARY SERVICING, REPAIR, OR CORRECTION. |
| 840 |
|
| 841 |
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING |
| 842 |
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR |
| 843 |
REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENSE, BE LIABLE |
| 844 |
TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR |
| 845 |
CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE |
| 846 |
SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING |
| 847 |
RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A |
| 848 |
FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF |
| 849 |
SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH |
| 850 |
DAMAGES. |
| 851 |
|