Facebook Cookbook - Jay Goldman [135]
Table 9-2. Parameters for login URL
Name
Type
Default
Description
api_key
string
N/A
Your application’s API key (not ID). This is required.
v
float
N/A
The API version you’re using. “1.0” is currently the only supported value. This is required.
auth_token
string
N/A
This is used only for desktop applications and is required when they make API calls. You can create this using the auth.createToken() method.
popup
bool
false
Forces the display of an alternate version of the login page without the Facebook navigation around it. For best results, you should open this in a pop-up window sized 646×436 pixels.
skipcookie
bool
false
Force Facebook to ignore the presence of a login cookie and always show the form. Might be useful if another Facebook user forgot to log out.
hide_checkbox
bool
false
Force Facebook to hide the “Save my login info” checkbox on the login form. Do this only if you want to force users to log in every time; otherwise, leave this as true.
next
string
false
Whatever you pass in here will get appended to the callback_url after login, so use this to maintain state.
canvas
bool
false
Force Facebook to return users to the Canvas page they came from rather than to your callback URL.
It’s worth going into a little detail about how Facebook assembles the URL that users will be sent to after they log in. By default, this will just be the callback URL that you’ve specified for your application (which should be off-Facebook). For the sake of this example, let’s assume that it’s something like:
http://facebook.myserver.com/apps/myapp
Users will be directed to that URL after they’ve logged in, and you’ll get an auth_token automatically added to the end of it:
http://facebook.myserver.com/apps/myapp?auth_token=aca27a78c5853267656280baa35642cb
If you specify a next parameter, Facebook will append that to the end of your callback URL. You’ll need to URL-encode the string so that it doesn’t become part of the login URL when you put your login button onto your Canvas page, which you can do using any number of web-based tools, such as http://ostermiller.org/calc/encode.html. Continuing in the vein of our example, let’s say that you wanted to append the time in epoch seconds, which you’ve calculated as 1212020040 (see Formatting Relative Time for more info about epoch seconds). In that case, you would pass “%3Ftime%3D1212020040” as the value for next, and Facebook will send users to:
http://facebook.myserver.com/apps/myapp?time=1212020040&auth_token=aca27a78c5853267656280baa35642cb
Note that Facebook will automatically switch the separator before the auth_token from ? to & if it needs to.
Finally, if you specify true for the canvas parameter, Facebook will send users back to the page they came from rather than to your callback URL. You won’t get an auth_token in that case (because you don’t need to create a session key when you’re making API calls from inside a Canvas page), but you will still get whatever you passed into next:
http://apps.facebook.com/myapp/?time=1212020040
Creating a Session Key
Problem
I need a session key so that I can make subsequent API calls from my app’s server to Facebook. Where would I find such a thing?
Solution
If you’ve made a run down to the local Session Key Store and they’re all out of stock, try the Auth.createToken() and Auth.getSession() methods. Desktop apps need to call Auth.createToken() to generate a token, whereas web apps will receive one appended to their callback URL when users log in (see Authenticating Users for more info).
Discussion
Session keys were undergoing some changes as this book was being written, largely to make the process of adding new applications and authenticating easier for users. Facebook has modified a number of its API methods so that they no longer require a session key (meaning that you can call them on behalf of users without users needing