;As the title suggests, this article will demonstrate the development of an FBML
Facebook application in ASP.NET using the Facebook Development Toolkit. We
will create a simple application that accesses the user's profile and displays a
list of the user's Facebook friends and their profile photos in a Facebook
"Application Invite" container. Before jumping in, it's probably a good
idea to define a couple of the terms we're going to be throwing around:
-
FBML (Facebook Markup Language): Somewhat similar to other markup languages like
HTML and XML, FBML exposes the Facebook API to developers, enabling access to
user profile data. Facebook interprets the FBML code, performs the
requested operations, and renders the results to the client browser as HTML.
-
Facebook Canvas: The container provided by Facebook which hosts the FBML
application.
-
Facebook Development Toolkit (FDT): An ASP.NET implementation of the Facebook
API. The current version as of this writing is 3.0.
There are several steps we will need to take. I'll list them first, and then we'll go
into detail:
Register your application with Facebook
Download and install the Facebook Development Toolkit
Develop the application
Register your application with Facebook
In order to have an application run in the Facebook Canvas, you need to first
register it with Facebook using their Developer Application on their web site.
It's free, but of course, in order to do this you must have a Facebook account.
The Facebook Developer Application is where you enter
information about your application. I'm not going to go into too much detail about the
Facebook Developer App - there's enough documentation on the Facebook web site - but
I will go over which tabs are essential and explain a little about each of those:
- Basic Tab: The Basic tab is where you enter the name of your application
and a short description of your application. You also must upload an image to serve as your
application's logo. The Basic Tab is also where you can find your Application ID, your API Key,
and your Secret Key. It will be necessary for your application to pass this data to Facebook
in order to identify itself.
- Authentication Tab: This tab allows you to specify how Facebook users will be able
to install your application. There are two installation options - "Users" and/or "Facebook Pages".
These options refer to whether a user can install the application to his or her profile, and
whether a user can install the application to their Facebook page. A user can select one or
both of these options. The Authentication Tab contains two other fields named Post-Authorized
Callback URL and Post-Removal Callback URL. These fields enable you to specify URL's to pages
on your web site which will get called upon a user's installation and removal of your application.
- Canvas Tab: The next essential tab is the Canvas Tab. The Canvas tab is where you specify
things like the Facebook URL of your application, the actual URL of your application on your web
server (to which users will be redirected if they link to your application's Facebook URL), and
a Render Method, which can be either IFrame or FBML. This article is not concerned with
the IFrame method, but it should be noted that, of the two, the IFrame method is simpler, albeit
less tightly integrated with Facebook than the FBML method. The FBML method however, allows a
developer greater access to Facebook's API, enabling you to include a Facebook user's profile
information, friends' names and photos, etc.
- Advanced Tab: The Advanced Tab allows you to specify whether your application is a
web or desktop application. It also gives you the option of enabling Sandbox mode. If Sandbox mode
is enabled, only those users you designate as developers of your app will have access to it.
Typically you would enable Sandbox mode while your application is still in development. Once
it's ready to go live, you can go to the Advanced Tab to disable Sandbox mode, thereby granting
access to all Facebook users.
Download and install the Facebook Development Toolkit
This step speaks for itself. Just download the FDT, unzip it, and place
the extracted binaries in a convenient location. There are five DLL's
included in FDT 3.0. We'll be using only three of them for this demo;
Facebook.dll, Facebook.Web.dll, and Facebook.Web.Session.dll. You can download the FDT here:
http://facebooktoolkit.codeplex.com/Release/ProjectReleases.aspx?ReleaseId=35534.
Develop the application
The application we develop here will not require much coding, but it will do
some pretty interesting things; sort of a "Hello World" on steroids. I'll get
you started and show you how to do the integration with Facebook by showing you
how to retrieve the logged in Facebook user's profile information, as well as
their list of friends along with their friends' profile photos. Once
you've gotten that down, the rest is just a matter of learning the rest of the
Facebook API.
First, create a new Web Application project in Visual Studio 2008. Then,
in order to make use of the Facebook Development Toolkit, we'll need to add
references to two of the DLL's contained in the FDT - Facebook.dll and
Facebook.Web.dll.
Next, add a new Webform to the project, and name it Helloworld.aspx. Since
this is going to be a Canvas application (it runs within the Facebook canvas),
the first thing we need to do with the helloworld.aspx file is to remove the
<head> tags (opening and closing) and everything within them. We also need
to remove the opening and closing <body> tags. Yes, it's weird, but it's
necessary. The reason for this is that since your app will be running
within Facebook, and the Facebook page will already have its own <head> and
<body> tags... well, you get the idea. Just so you know, this is going to
cause Visual Studio to complain about some of your code. Without the
<head> and <body> tags, VS gets a little confused about what's valid markup and
what isn't. Ignore it. Although the editor complains, the compiler builds
everything just fine with no errors or warnings.
And now for some code. Take a look at the listing below. Explanation to follow:
Helloworld.aspx
The listing above is the complete Helloworld.aspx file. As you can see, it
consists solely of two <asp:Label> server-side controls. The interesting
part comes next when we populate those labels in the code-behind file.
Take a look at Helloworld.aspx.cs below:
Helloworld.aspx.cs
By examining the above listing, we can see that first we need to include the two
DLL's from the Facebook Development Toolkit,
Facebook and Facebook.Web. Next, instead of extending System.Web.UI.Page as we
normally would, we extend Facebook.Web.CanvasFBMLBasePage. As we begin the interaction,
we first create an FBMLCanvasSession instance by passing in the API Key and Secret Key parameters
to the constructor. These are the parameters you got from Facebook when you registered
your Facebook application. In this example I've stored them in the web.config file, so
I'm reading them using the ConfigurationSettings object. Next we pass our FBMLCanvasSession
instance to a Facebook.Rest.Api constructor to obtain a valid Api object on which
to operate.
Now that we have that Api object we're ready to rock and roll. The fbAPI.Users.GetLoggedInUser()
method returns the logged in user's user id. Passing that user id to the
fbAPI.Users.GetInfo() method gets you the user object for that user. You can get
pretty much any user information you might need from the user object. In our example,
I'm using it to return the user's profile photo and first name. Pretty cool, huh? And not
too difficult either.
Now it gets even cooler. In our ShowApplicationInvite() function, we build a string
that contains the Facebook API call (in FBML) that we need to make in order to display an Application
Invite Box within our application. This Application Invite Box will contain a list
of the logged in user's friends along with their pictures. The user will
have the ability to choose which of their friends to share your application
with. Next we build a string that contains the API functions
(again in FBML) which create a request-form, and pass it the content we received in the
first API call. Finally, we close the request-form, by appending another api call to
the string. We then return that entire string back through our Page_Load function and
assign it's value to the text property of labelFriends. When you compile this
and publish it to your server, assuming you have some Facebook friends, you can log into your
Facebook account, run your program (http://apps.facebook.com/helloworld) and be
amazed.
Hopefully this article makes this topic somewhat less confusing, rather than
more.
Dave Verschleiser
Murray Hill Technologies