source: perl/modules/Facebook/lib/Facebook/Graph/Cookbook/Recipe1.pod @ 7777ac2

release-1.10release-1.9
Last change on this file since 7777ac2 was 2a42248, checked in by Edward Z. Yang <ezyang@mit.edu>, 13 years ago
Add vanilla Facebook::Graph. Signed-off-by: Edward Z. Yang <ezyang@mit.edu>
  • Property mode set to 100644
File size: 7.9 KB
Line 
1=head1 NAME
2
3Facebook::Graph::Cookbook::Recipe1 - Building Privileged Applications
4
5=head1 VERSION
6
7version 1.0300
8
9=head1 DESCRIPTION
10
11Let's build a privileged Facebook application from nothing.
12
13=head2 Things To Think About
14
15Though templating systems such as L<Template::Toolkit> and web frameworks such as L<Dancer> and content management systems such as WebGUI L<http://www.webgui.org/> are out of scope for this document, when you build your own application, you should definitely consider using them.
16
17For simplicity sake, in this recipe we'll be storing important information directly in the code. This is a terrible practice. Instead use a config file system like L<Config::JSON> to store your settings.
18
19=head2 Assumptions
20
21This recipe assumes that you know and have L<Plack> installed and that you have a Facebook (L<http://www.facebook.com>) account.
22
23You'll also have to be able to point a domain name to a server that is accessible from the Internet. DNS and server configuration are way beyond the scope of this document.
24
25=head1 RECIPE
26
27=head2 Step 1: Set up the developer application on Facebook.
28
29Go to L<http://apps.facebook.com/developer>.
30
31Click "Allow".
32
33=head2 Step 2: Create your application.
34
35Go to L<http://www.facebook.com/developers/createapp.php> or click "Set Up New Application" from the developer application.
36
37Fill in an application name. The only restriction is that it can't use a Facebook trademark or be similar to official Facebook application names.
38
39Agree to the terms of servce.
40
41Click "Create Application".
42
43=head2 Step 3: The Connect tab.
44
45After creating your application, go to the "Connect" tab.
46
47Fill in the "Connect URL" field. It should be something like C<http://www.yourapplication.com/facebook/>. It is the base URL to where you'll be deploying your application. The trailing slash is required.
48
49Click "save".
50
51=head2 Step 4: Note your application settings.
52
53You either want to make note of your "Application ID" and your "Application Secret" or bookmark this page so you can come back to it. You'll need these later.
54
55=head2 Step 5: Create app.psgi.
56
57Create a file called C<app.psgi>. Start it off like this:
58
59 use strict;
60 use Plack::App::URLMap;
61 use Plack::Request;
62 use Facebook::Graph;
63 use URI;
64
65 my $urlmap = Plack::App::URLMap->new;
66 
67 # your code will go here
68
69 $urlmap->to_app;
70
71All the code we have you add should go in the C<# your code will go here> block, in the order that we have you add it.
72 
73=head2 Step 6: Create your Facebook::Graph object.
74
75Now we can finally start building L<Facebook::Graph> into our app.
76
77 my $fb = Facebook::Graph->new(
78    postback    => 'http://www.yourapplication.com/facebook/postback',
79    app_id      => 'Put Your Application ID Here',
80    secret      => 'Put Your Application Secret Here',
81 );
82 
83Now you need the URL you entered in step 3, and the application ID and secret you got in step 4.
84
85On the end of the url, add C<postback>. This could be anything really, but it needs to be separate from the Connect URL.
86
87=head2 Step 7: Create your application's connect page.
88
89Now we need to create the authorization redirect. This is where we tell Facebook what permissions we want. There is a complete list of permissions documented at L<http://developers.facebook.com/docs/authentication/permissions>.
90
91If we only wanted basic permissions we can leave the C<extend_permissions> call out. But for this app let's say we want access to the user's email address and we want to be able to interact with the user's account even when they aren't online.
92
93 my $connect = sub {
94    my $env = shift;
95    my $request = Plack::Request->new( $env );
96    my $response = $request->new_response;
97    $response->redirect(
98        $fb
99        ->authorize
100        ->extend_permissions( qw(email offline_access) )
101        ->uri_as_string
102    );
103    return $response->finalize;
104 };
105
106 $urlmap->map("/facebook" => $connect);
107
108We map the subroutine we created to C</facebook> because we'll likely have other things we want to display at C</>. If we wanted to display something else at C</facebook> we could have mapped this function to C</facebook/authorize>. It really doesn't matter what URL we use here, all that matters is that when we want our users to authenticate against Facebook, this is the URL that we're going to send them to in our application.
109
110=head2 Step 8: Create the Facebook access token postback page.
111
112Our connect/authorization page will redirect the user to Facebook to authorize our app. Now we need to create the page that the user will be redirected back to from Facebook. This is the C<postback> that we created in step 6.
113
114 my $postback = sub {
115    my $env = shift;
116    my $request = Plack::Request->new( $env );
117
118    # turn our authorization code into an access token
119    $fb->request_access_token($request->param('code'));
120
121    # store our access token to a database, a cookie, or pass it throuh the URL
122    my $uri = URI->new('http://www.yourapplication.com/search');
123    $uri->query_form( access_token => $fb->access_token );
124
125    my $response = $request->new_response;
126    $response->redirect( $uri->as_string );
127    return $response->finalize;
128 };
129
130 $urlmap->map("/facebook/postback" => $postback);
131
132It's really stupid of us to pass our access token along the URL especially since we requested C<offline_access>. We're only doing it here to demonstrate the usage of it. If you're requesting offline access, you should keep the access token locked away in a secure database. If you want to pass it along the URL, or store it in a cookie, you should B<not> request C<offline_access>.
133
134=head2 Step 9: Let's do something already!
135
136So now that we finally have an access token we can start making privileged requests. That works like this:
137
138 my $search = sub {
139    my $env = shift;
140    my $request = Plack::Request->new( $env );
141
142    # display a search
143    my $out = '<html>
144    <body>
145    <form>
146    <input type="hidden" name="access_token" value="'. $request->param('access_token') .'">
147    <input type="text" name="q" value="'. $request->param('q') .'">
148    <input type="submit" value="Search">
149    </form>
150    <pre>
151    ';
152
153    # display the results if a search is made
154    if ($request->param('q')) {
155        $fb->access_token( $request->param('access_token') );
156        my $response = $fb->query
157            ->search($request->param('q'), 'user')
158            ->limit_results(10)
159            ->request;
160        $out .= eval{$response->as_json};
161        if ($@) {
162            $out .= 'ERROR: '.$@->[1];
163        }
164    }
165
166    # close everything up
167    $out .= '
168    </pre>
169    </body>
170    </html>
171    ';
172
173    my $response = $request->new_response;
174    $response->status(200);
175    $response->content_type('text/html');
176    $response->body($out);
177    return $response->finalize;
178 };
179
180 $urlmap->map("/search" => $search);
181
182
183=head2 Step 10: Start the application and let's test this puppy out.
184
185On your server (the one that www.yourapplication.com points to) run the following command (assuming you're in the folder with app.psgi).
186
187 sudo plackup --port 80 app.psgi
188 
189Now we point our browser to:
190
191 http://www.yourapplication.com/facebook
192 
193Voila! You have created an authenticated Facebook app. If you would like to see this full program check out C<eg/recipe1.psgi> inside this distribution of L<Facebook::Graph>.
194
195
196=head1 CAVEATS
197
198You should never design an application using all the poor stuff we've done here, like using a shared L<Facebook::Graph> object, not using a Framework/CMS or at least L<Plack::Builder>, not using a templating system, passing the offline access token through the URL, etc. We've made comments about these things as we did them to warn you. These choices were made here B<only> because this is example code who's primary purpose is to show you how to use L<Facebook::Graph>, and not best practices for web development.
199
200=head1 SEE ALSO
201
202For more recipes, check out the L<Facebook::Graph::Cookbook>.
203
204=head1 LEGAL
205
206Facebook::Graph is Copyright 2010 Plain Black Corporation (L<http://www.plainblack.com>) and is licensed under the same terms as Perl itself.
207
208=cut
Note: See TracBrowser for help on using the repository browser.