Quick review of the Facebook platform
I'm working on a project now for a client that involves Facebook, and it's one of those dream projects where they pay you to learn while also working on a final product. I've spent about 10 hours so far reading, playing, and scratching my head more than once, and I thought I'd share my thoughts on what I've seen so far. Please keep in mind that I'm still learning this myself, so forgive me if I get any details wrong.
First and foremost - what in the heck is the Facebook platform? You may think that it is simply another API, like the various Google or Yahoo services. Not exactly. When you build a Facebook application, what you are really doing is building an API yourself.
Let me explain. A Facebook application runs on your server. You have to set up a web server for it. Because it is your server, you can use any language you want. But it has to be ColdFusion. Really. (Ok, maybe not.) But all interaction is done via Facebook.com. So imagine some random application, like The Wit and Wisdon of Paris Hilton. When a user runs this application, Facebook will talk to your server. So in other words:
- User runs application by hitting a URL on Facebook.
- Facebook passes off the request to your server, and sends some extra flair along
- Your server responds with text, beautiful text
- Facebook renders the text back to the user
So a Facebook application is almost like a proxy. If your application lets you do 3 things, then Facebook simply acts as a go-between for the user and your application. Now I say "simply a go-between" but that isn't really true. It does send along information that your application can use, but I'll cover that a bit more later.
Things get interesting in what you do with your response. Your Facebook application can respond with simple text and HTML. But you can also add FBML to your response. FBML is Facebook Markup. Let me give you an example. Imagine my application responded with:
<fb:dashboard>
<fb:create-button href="#">Hello world!</fb:create-button>
</fb:dashboard>
While fb: means nothing to ColdFusion, when Facebook gets this back, it will render a button on the application page. The <a href="http://wiki.developers.facebook.com/index.php/FBML">FBML docs</a> discuss the entire set of tags. It's pretty impressive. You can also do some pretty fancy things like:
<code>
<p> Hello <fb:name uid="#request.userID#" useyou="false"/>!</p>
Don't worry about the request variable for now. Just know that it represents the Facebook user. Facebook will replace fb:name with, you guess it, the name of the user.
Ok, so far so good. You have an application. It outputs text. Facebook looks for fb: tags to replace. That part is rather simple. Here is where things get crazy.
I mentioned above that Facebook will hit your application and pass along some information. It doesn't pass along an entire user's profile. It does pass along a user id. Facebook provides a REST based API where you can request other bits of information. So the scenario works like this:
- User requests your application on Facebook
- Facebook pings your server, sending along a user ID
- Your code grabs the user ID, and makes a REST request to Facebook for user profile information for the user ID sent.
- Facebook responds with the info.
- You parse the response and output text, perhaps saying "Hi" if the profile was for a man, and "Hi ;)" if the profile was for a woman
- Facebook returns the response to the user
So that one simple request actually ended up with some fancy back and forth action there. Along with the REST api, Facebook also has a way cool thing called FQL, or Facebook Query Language. This is a SQL-like API that lets you do more complex operations in a quicker form. So for example, I can write a SQL statement to get all the friends of user id X and then filter by the women (or men, or whatever). Here is an example of that:
select name, pic
from user where uid IN (SELECT uid2 FROM friend WHERE uid1 = X) and sex = 'Female'
The X value is really a user ID I removed.
So how do you get started? Begin at their Developer site. To start an application, you actually have to add an application to your profile - the Developer Application. (It's kind of cool that the tool you use to work with the platform actually uses the platform itself.)
Once you've added the Developer Application, you can then create an application. For some silly reason they don't include a "Add Application" link, but instead ask you to request a application key. You will be asked to define various settings. I'm not going to do a full walkthrough now as that would be a bit long, but in general, just take the defaults where you can. The critical setting is the callback url. This is the root url for your own code. So for my sample application, The Wit and Wisdom of Paris Hilton, I used:
http://www.coldfusionjedi.com/demos/paris/
(Be sure to use the trailing /.) I then gave a Canvas URL value of
http://apps.facebook.com/witandwisdomofparis
So here is the cool thing. Whenever someone requests the Canvas URL, Facebook will call off to your own URL. If I went to
http://apps.facebook.com/witandwisdomofparis/foo.cfm
Then Facebook will hit
http://www.coldfusionjedi.com/demos/paris/foo.cfm
You get the idea. In order for things to work, you obviously need code. I used Facebook FBML Starter Kit from Dominic Wilson. It has a few kinks in it still (I've bugged him on it) but it worked great for me to start off with. Be sure to edit the code to supply your application values. If you've done everything right, you should be able to see a basic display here:
http://apps.facebook.com/witandwisdomofparis
Now here is where I had some issues. I added my application to my profile, but nothing showed up. The only way I could tell I had the application was by editing my list of applications. (Not the Developer one - those are your applications.)
Turns out there are certain "rules" about how stuff shows up on your profile. First off, if you want the application to show up in the left hand menu, you have to supply a side nave URL. The URL must be on Facebook. I used the same URL as my Canvas URL (think of the Canvas as your home page):
http://apps.facebook.com/witandwisdomofparis/
You can use a different URL if you have some other action in mind. Now - why didn't I see anything on my profile page proper? This is the part that really confused me.
From what I get - there is a setting for applications called Default FBML Basically it's the text to show up on the profile page. I edited my application and used "Hello World!". When I did that, it showed up on my profile. As you can guess, you can put FBML in there. Here is a really cool example:
<fb:wide>
This will only appear in the wide column.
</fb:wide>
<fb:narrow>
This is the smaller one.
</fb:narrow>
This FBML lets me show different text based on what side of the profile I am. I didn't even know you could drag stuff back and forth.
So that's the profile. When a user visits the Canvas page, this is where you choose what to show. As an example, here is what I did for the Paris page:
<cfset wisdom = "Every woman should have four pets in her life. A mink in her closet, a jaguar in her garage, a tiger in her bed, and a jackass who pays for everything.@I think it's important for girls to be confident. Believe in yourself and ... everybody's hot.@Wal-mart... do they like make walls there?">
<cfset yourwisdom = listGetAt(wisdom, randRange(1, listLen(wisdom,"@")), "@")>
<cfoutput>
<div style="padding:10px">
Random Paris Hilton Quote:
<blockquote>
#yourwisdom#
</blockquote>
</div>
</cfoutput>
I didn't use any FBML here at all - just quick and dirty output. But if you add the application to your account and click on the menu link, you will see a random quote every time you reload.
So... I had called this a 'quick' review, and it was anything but. I obviously only touched on a few topics, but let me leave you with some last thoughts/questions.
1) It is a royal pain in the rear to test with other accounts. Facebook does not allow you to have test accounts. They will delete them when they find them. But they do let you create an account and then flag it as a test account. These test accounts exist in their own universe though. They use different friends, etc. That's fine an all. The sucky thing is that you still have to use real email addresses. Until Facebook fixes that, be prepared to go to your mail server and set up a few additional accounts.
2) My sample code - the random Paris quote - is a perfect example of one thing I'm still confused about. The Canvas page is always dynamic. Everytime you load it at Facebook, they hit your site. The profile page though is not. I've seen Flash embedded in the profile, and so I suppose you could use Flash to call your server and get a response that way. Outside of that though the only other way to set the text there is with the REST call. So either you initiate it with CFSCHEDULE, or use Flash.
3) Lastly, don't forget the issue ColdFusion has with Facebook, discussed here: Fixing the Facebook Problem, and why one ColdFusion feature needs to die... The template I used took care of that issue for me.
4) Some random things I kind of forgot. :) You do get some nice stats about your application, like signups, removals, etc. You can even specify a URL on your site to hit when someone adds or removes the application. That can be very handy with tracking as well.
Comments
Thank you Ray, I've been meaning to make a facebook app and this is very easy to understand basic walk-through
This is pretty good info. Thanks. I wonder how far can someone go with this. I will have to dig more into the FBML
One more thing to be aware of:FB has 7 secs timeout for any request to your server, so your application has to be really quick with good hosting close to FB =)
Yes, but I use ColdFusion, and 7 seconds would be an eternity for CF. ;)
Don't forget that any REST call (getting user info, list of friends, any other data) will be made to FB server within these 7 secs, so add XML round trip time and FB processing time.
Shameless plug, check out http://coldface.org or at least http://apps.facebook.com/coldface-exmaple-app/ I invite anyone in the CF community to get involved. Thanks.
Please . . . tell your client to go easy on the invites . . . make it hard for one to automatically send invite to every single person that you're linked with.
A slightly different requirement about FB interface. What if I want to extract a few msg from my FB inbox. How do we go about that?Thks.
Don, I'd check their docs to see if they support it.
The application I've posted above exercises all known Facebook API methods. There's nothing in there to get access to your FB inbox.Cheers.
This is a damn sight better explanation of the basics than Facebook's own documentation!Thanks Ray.
Thanks.
Am I the only one that loads this Facebook FBML Starter Kit, changes the stuff and gets no authorisation every single time? It seems to be checking a form, but that form is always blank (cfdump) as well as the application.FBMLClient which shows me less info than I expected when I dump it.
I am guessing this is one of those "simple" things I need a line of code, or a correction or something and things will be lickity splitity. Anyone have advice on this? (CF8 btw)
Can you be a bit more clear? No authorisation?
Invokes lines 10 to 14 on fb_post.cfm<cfif not application.FBMLClient.AuthenticatePost(form, 'SIG_FB')>
<h1>Authorisation error</h1>
<p> You are not authorised to view this page.</p>
<cfabort>
</cfif>
So something in the form isn't there, I do a cfdump of #form# and I
get a blank struct.
Feels like something isn't initialized, but I am pretty sure that is solid (callbacks and keys and whatnot).
HA! solved it.I had been using another API: Cory Johnson's which require an iframe. So of course, no post.
I re-read the code and thought "this looks like FMBL native" so I changed the app over and YAY!.
So, note to self, this needs the FMBL setting and won't work on iframe.
Have you got the photoTag feature working?I want to use CF to add photoTag features for graduation photos.
You can use the rest API to upload photos. I've done it succesfully in ColdFace http://coldface.org/ I think you can tag or at least give the photo comments when you upload it.
Great explanation!.Thanks a lot.
Kinds,
Jorge
I keep getting this everytime. Any ideas?Errors while loading page from application
Received HTTP error code 405 while loading http://www.thewarp.org/facebook/cfm_template
There are still a few kinks Facebook and the makers of Actionscript are trying to iron out. We appreciate your patience as we try to fix these issues. Your problem has been logged - if it persists, please come back in a few days. Thanks!
Found the solution.You have to specify index.cfm in the callback URL:
http://www.thewarp.org/facebook/cfm_template/index...
I think that it assumes that it is a PHP page.
If it wasn't for this article, who knows...I'm using the provided cf test app but whenever i click on "Go to application" nothing happens.
http://apps.facebook.com/tasosbotisfacts/
Any idea? help?
Thanks,
Alexander
Heh, it's funny someone just read this. I'm actually working on a new version of this article. I don't know if i can talk about where/when, but I'm in the process of updating it.So one thing I'd suggest is, do some heavy logging on the CF side to ensure you are seeing the HTTP requests come in.
Great - without pressuring, hope we see something soon! Logging seems like the best trick, so to make this comment a bit useful this is how i plan to log:<cfdocument format="pDF" overwrite="yes" filename="thefile.pdf">
<cfdump var="#form#"/>
<cfdump var="#cgi#"/>
<cfdump var="#url#"/>
</cfdocument>
and for errors:
<cftry>
<cfcatch type="any">
<cfdocument format="pDF" overwrite="yes" filename="errordebug.pdf">
<cfdump var="#cfcatch#"/>
</cfdocument>
</cfcatch>
</cftry>
Oh god no - you don't want to use pdf for logging. I'd use cfdump's new file based logging ability.
Too late :), but indeed a better way.<cfif not StructKeyExists(form, "fb_sig_user") or not StructKeyExists(form, "fb_sig_session_key")>
this seems to always validate as there is no fb_sig_user nor fb_sig_session_key, therefore always redirects here: http://apps.facebook.com/tasosbotisfacts/
In the form parameters i see FB_SIG_ADDED is 0. How can i get to the page where it shows you the facebook terms and the "Allow" button?
Um, if I remember right, the first hit on your app will prompt the user. If you already have the app added to your account, remove it, and hit it again. I went to your URL and I see that msyelf.