How to Use the Facebook Connect API in an ASP.NET Web Application


Nov 5, 2013 (3 years and 7 months ago)


How to Use the Facebook Connect API in an ASP.NET Web Application

Build social networking capabilities into your ASP.NET web applications

These days it
goes without saying that social networking is a trend, with Facebook as one of the leaders in
connecting people to the rest of the world. Facebook allows you to connect with people on so many different levels,
giving you a portal to befriend people, let th
em know your likes and dislikes, show them the causes you believe in,
show them what you are a fan of, and so much more. Facebook is also extensible; developers can create customized
applications that load within the Facebook infrastructure, or outside of
it. These applications are not explicitly created
by Facebook developers, but by any developer who signs up.

There are two types of Facebook applications: The first type is within Facebook framework itself, on the same site.
This application uses either th
e Facebook Markup Language (FBML) or JavaScript (or even both) to create an add
of your own specific design that will run and operate within the


The second type of application is the one th
at resides outside of the Facebook realm altogether. This is referred to as
a Facebook Connect site. This site requires the use of a JavaScript API or XFBML (or a combination of the two). This
type of site uses a REST API to connect to Facebook, extract in
formation (such as logging in users and querying their
profile), and much more.

You may wonder why integrate with Facebook? There can be several reasons. First, the world has changed with the
creation of social networking sites, in the way we think and con
nect with other people. Facebook is a popular means
of doing that and is another way to connect to an additional audience: by cross
connecting between Facebook and
your custom website. Another reason you may want to use Facebook Connect is as an authentica
tion store; a good
portion of the world is on Facebook, and so you can use this site as a way to verify someone's identity or use them as
an account. Whatever your reasons, it's helpful to understand what you need to be able to do to communicate with
ook to get your ASP.NET website running.

What's the Difference?

You may be wondering about the differences between the Facebook API and the Connect API. The two APIs are
very similar, actually. The difference, however, comes in the way that the application
s are used. Facebook Connect is
meant for applications being developed outside of the domain. These applications are commercial or
personal applications using the Facebook API to embed social networking features into this application, the subj
we'll talk about in this article. Facebook, however, uses a separate but similar API for creating applications within the
site. I'll explain the differences between these APIs shortly. For now, know that development can take place in the
realm of Faceb or outside for another personal site.

Understanding the Facebook Connect API

More and more sites are providing a REST
based API that creates the UI. The data gets returned as a JavaScript
object, and some UI appears with this accompanying data. The

primary means to creating the interface or
communicating to a REST server is JavaScript. JavaScript has the ability to render HTML in the browser, so as to
generate a UI on the fly. With Facebook, JavaScript is one of the solutions to rendering a UI. Face
book's script
contains the necessary components to extract information from Facebook's servers about your application, its users,
and their information. This is an important piece to the puzzle, but not the only means to access information. Some of
the cor
e components are:

FB: the namespace for all Facebook core components.

FB.Connect: represents the connect object or child objects that work with the connect API. We will
be using some methods in this API.

FB.Facebook: the core object for Facebook applicat
ions, which contains some other useful features
for Connect applications.

ApiClient: This is a core object for working with Facebook. This object provides method calls that
communicate with the Facebook REST server, to extract information such as retrievi
ng a user's list
of friends, the groups they belong to, their events, and much more.

Every user who logs into Facebook has an ID. This ID is a numerical value (outside of username/password
combination) that represents the user logged into the site. This I
D is used to retrieve information about the user, and
is very important to have. We'll illustrate how to get this later.

The next option is the FBML/XFBML languages. FBML stands for Facebook Markup Language and is a Facebook
specific syntax for creating ap
plications. FBML consists of a series of tags that are within the namespace. For Facebook Connect applications, the XFBML syntax is used,
which consists of a smaller tagset than what is available for Facebook applications
embedded into
One of the more common examples of XFBML tags is the <fb:login
button /> element. This element renders a
connect button as well as all the other required scripts to properly handle the login process. We'll explore some of the
ailable tags later in the article.

Facebook Tools

All Facebook developers must first go to the developers' website at
Becoming a fan of the application gives you the abi
lity to create your own application and have access to other useful
resources. On the right side of the page is a button to create a new application. Create the application by clicking it.
The wizard brings you to a page where you can enter the name of the

application. Give the application a name and
click the Save Changes button, as Figure 1 shows.

After the application

is created, go to the application's main page. You'll see an Edit Application Name profile link.
Click this link, followed by clicking the edit button for Application Settings. In the connect configuration settings, the
main setting to establish is the co
nnect callback URL. This URL is the main URL to your site. I've established a free
domain for my personal testing (e.g.,
); make sure you point to the root folder structure
and not to a spec
ific file within your website. This URL is meant to point to the site that uses the Facebook
application, so it spans across multiple files.

You only need to specify the connect URL at a minimum; however, feel free to provide other settings as well. Take a

look at some of the Connect settings in Figure 2.

When you access this developers' application, there are some handy
tools that Facebook has made available. The
first is a form that allows you to enter FBML/XFBML markup, which Facebook translates into its HTML/JavaScript
equivalents. This translation isn't a client to server rendering, but illustrates what happens under
the scenes with each
Facebook tag. Facebook also has a Wiki with useful information, along with a forum for you to ask questions to other

Logging In

Facebook provides a couple of ways to log into your Facebook connect site. The process of conne
cting to a
Facebook Connect site and extracting Facebook services begins when you connect to it. Let's begin by looking at the
basic connect login page in Figure 3 below.

Figure 3: Basic Connect page

button onlogin="post_login();"></fb:login

<script src="

FeatureLoader.js.php/en_US" type="text/javascript"></script>

<script type="text/javascript">

var api_key = '1234567890abcdefghijklmnopq';

var channel_path = 'xd_receiver.htm';

], function() {

// Create an ApiClient object, passing app's API key and

// a site relative URL to xd_receiver.htm

FB.Facebook.init(api_key, channel_path);


function post_login() {

window.location = 'profile.aspx';



At the bare minimum, this is what Facebook Connect requires to log in to the page. This is a simple HTML page that
embeds a static script from in it, which contains all the necessary objects to setup the
. As I mentioned before, <fb:login
button> renders a button the user can use to login to the website. When
the button is clicked, a connect screen appears asking you to log into this application and give it permission to use
your information. An alternativ
e to the login button would be to make a call to FB.Connect.requireSession, which
performs a similar feature. Whether the button is used or the direct call, both options provide a valuable way to
connect to Facebook.

In order for Facebook integration to wo
rk, some initialization information is needed, through the use of an API key and
a channel path. The API key is the key that gets generated when you create a new application on the Facebook
developers' site. The xd_receiver.htm file is a special file that
Facebook requires for cross
domain communication. I
am omitting it from this article due to time and space constraints; however, you may download it from the sample files
I've provided with this article (click the Download link at the top of the article) o
r view it in the Wiki. It's pretty
straightforward, and basically you copy the markup directly from the Wiki.

FB_RequireFeatures is the first Facebook method we'll examine here; it's a useful method that delays execution of
scripts until those features are

available to the developer (which may be delayed for multiple reasons). The first
statement specifies that the initialization should be delayed until able to process XFBML script, accepting a callback
that will run when script can run successfully.

ebook is a core object for using the Facebook API, but for Connect applications you will be interchanging
FB.Facebook andFB.Connect. FB.Facebook has an init method that initializes the application, specifying the ID of the
application and the path to the r
eceiver file (in this case, xd_receiver.htm is in the root along with the ASP.NET page).

Upon clicking the login button and logging into the server, the onlogin code fires, triggering the post_login method.
Any login code can run, and in this case, the use
r can now be redirected to the profile page, where most of the work


The profile page features a few new XFBML tags to introduce. Figure 4 shows the tags.

Figure 4: XFBML tags

<table cellspacing="0" border="0">






pic uid="loggedinuser" facebook
logo="true" size="normal"></fb:profile

<br />

<fb:name uid="loggedinuser" useyou="false"></fb:name>

<br />

button href="http://bmains/"><

<br />





permission perms="read_stream,publish_stream">Would you like our application to
read from and post to your News Feed?</fb:prompt

stream width="400" h





Each of these new tags has the following functions:

pic: This tag displays the user's profile, in either a small, normal, or large image format.

Fb:name: displays the name of a u
ser, including your name potentially. If useyou is set to true, if the
user is you, you see the text "You" instead of your name (which would appear when the property is
set to false).

Fb:share_button: renders a share button that allows users to share your

application to other users.

permission: displays a prompt to the user allowing the application to perform some
action. Facebook ensures that certain features require the application to prompt the user to allow
that permission.

displays the information on your wall to the user, as you see in Facebook.

These are only a few of the possible XFBML tags and are the only ones used in this example. The rest of the options
available can be found in the Facebook developers' Wiki.

ipt API

Facebook has an extensive JavaScript API, too. Our first feature of the Facebook API will be to extract the current
user's information and display it in the page. The core object to perform this feat is the ApiClient object, the object
through whic
h all of our REST
based, user
related data is retrieved.
Figure 5

shows an example of our first use of
this object.

Figure 5: Getting user


FB_RequireFeatures(["XFBML"], function() {

// Create an ApiClient object, passing app's API key and

// a site relative URL to xd_receiver.htm

FB.Facebook.init(api_key, channel_path);

n() {

var api = FB.Facebook.apiClient;

var userID = api.get_session().uid.toString();

api.users_getInfo(userID, 'last_name, first_name, about_me, birthday,
relationship_status, hometown_location', function(user, ex) {

if (ex != null) {

"An error occurred when loading the user:" + ex);







All the methods that retrieve data from the REST server use the callback approach, which takes the object returned
from the method and a potential exc
eption being thrown. Each REST
based method takes a different set of
parameters. The getInfo method takes a reference to the user's ID (a long value) and a comma
separated list of the
fields to download from the server. Most systems simply return the entir
e dataset for the user, but the users_getInfo
method requires you to specify the fields to download, and only these fields will be accessible.

Let's take a look at some other REST
based methods, starting with the one in
Figure 6

The groups_get and

methods get the groups and albums that belong to the user. Both methods use the user ID and
take a second parameter that accept
s an array of IDs to use to include in the list. The callback methods return an
array of group/album objects with a variety of useful parameters.

Figure 6: Loading other resources

api.groups_get(userID, null, function(groups, ex) {

if (ex != null) {

lert("An error occurred when loading the groups:" + ex);





api.photos_getAlbums(userID, null, function(albums, ex) {

if (ex != null) {

alert("An error occurred when loading the albums:" + ex);



ums(albums, api);


Some useful properties of the album object are:

cover_pid: references the ID of the photo for the album cover, in case you want to view the full
photo. In order to get a photo by its ID, use the photos_get method from the ApiClient ob

link: the link to the album on Facebook. Clicking it redirects to the site.

edit_link: the link to go directly into editing the album in Facebook. Clicking it redirects to the site.

name: the name of the album.

owner: th
e user ID of the owner.

Groups, however, have a different set of properties:

description: the description of the group, as entered when creating the group.

gid: the unique identifier of the group.

group_type and group_subtype: the type and subtype of gr
oup as entered by the creator.

name: the name of the group.

pic, pic_big, and pic_small: the URL to the picture of the group in various sizes.

recent_news: recent news as entered by the creator of the group.

Most of the REST APIs are very similar to th
is approach. There are quite a few APIs, and I can't touch upon them all
in one single article. I do, however, want to get to one last item regarding to the types of data available to developers:
friends. Naturally, every user who connects to this applicat
ion is bound to have registered friends. Let's look at the
code in
Figure 7
, which illustrates the use of methods that will let your app a
ccess friends.

Figure 7: Displaying friends

api.friends_get(new Array(), function(users, ex) {

if (ex != null) {

alert("An error occurred when loading the groups:" + ex);





function loadUsers(users) {

var container
= document.getElementById("friendspanel");

var api = FB.Facebook.apiClient;

api.users_getInfo(users.slice(0, 12), 'last_name, first_name, pic_square',
function(usersToDisplay, ex) {

if (ex != null) {

alert("An error occurred when loading the user:"

+ ex);



for (var u = 0, ulen = usersToDisplay.length; u < ulen; u++) {

var user = usersToDisplay[u];

var div = document.createElement("DIV");

var image = document.createElement("IMG");

image.src = user.pic_square;


var span = document.createElement("SPAN");

span.innerHTML = user.first_name + " " + user.last_name;






The friends_get method

does the work of retrieving a user's friends. The loadUsers method does the actual work of
displaying the users to the viewer of the web page. While I omitted the creation of the page using JavaScript for
groups and albums, the process is pretty simple, s
o I'll illustrate both processes in one last example here.

The friends_get method works similarly to the previous methods. It takes as its input an array of user IDs to limit a
result by. Although normally null is passed in this place, documentation on th
e Facebook Wiki recommends passing
in an empty array.

The response returns in the format of an array list of user IDs (longs) that are a person's friends. Although that
doesn't seem overly helpful, the users_getInfo REST method does the actual work of retr
ieving our friends'
information. If I didn't state it before, the list of information that you can retrieve about your friends is pretty long, bu
here we only want first name, last name, and a URL to their image.

Rather than using the FBML approach to cre
ating the UI, the data streamed from JSON is created via the JavaScript
DOM. The DOM has the ability to create and append elements to it. Via a simple approach I used the DOM to create
the user's image and display their name below that image. Each of these

image/name pairings is grouped in a DIV, a
very simplistic way to render the UI. Notice that the loadUsers method loads only 12 friends from the user's profile,
rather than loading the entire list, which could be hundreds or more.

Strategic Options

So wha
t does this enable us to do? These APIs allow you to get in touch with the people who use your application at
a whole new level; you can see what their interests are. You can see if they are even interested in your group,
product, or are your fan (or whate
ver the relationship may be between your application and your user).

There are so many opportunities to connect with your users. A good way to figure out what level to take your
application is to see what other businesses are doing and try to get some idea
s of what you can do with your product,
business, or even general interest.

With what you've seen today, you can see how you can match users to preferences (groups) by name matching. You
could even store a collection of groups that relate to your product a
nd identify who may be interested in that group.
These are just a few ideas, but the possibilities are endless.

Requesting Extended Permissions

Certain features in Facebook require some extended permissions. These permissions must be granted before the

call will succeed. One example is setting the user's status, as
Figure 8


Figure 8: Updating status with extended permissions

userstatusbutton").click(function() {

FB.Connect.showPermissionDialog('status_update', function(result, ex) {

var box = document.getElementById("userstatusbox");

var api = FB.Facebook.apiClient;

api.users_setStatus(box.value, false, false, function
(status, ex) {

if (ex != null) {

alert("An error occurred when setting the status:" + ex);



if (status)





jQuery attaches to the button click event, sends a call to submit the user's status
, and displays their status in a label
below the textbox (via the setStatus method call). One important note: If you call this method directly, the request will
fail. The reason it will fail is due to permissions. We first must wrap the code with a showPer
missionDialog request.
The "status_update" extended permission will show an alert box, asking the user if this permission is OK. Setting the
status will only work if the user agrees.

Facebook and ASP.NET

So what are the requirements with ASP.NET?

Not surp
risingly, Facebook works in ASP.NET, too, since the by
product is essentially HTML. Although ASP.NET requires only one form, MVC is not limited to this, so you could say
implementing this into MVC would be even easier than ASP.NET. The key to this is that
it's a client
side solution; this
solution isn't using the Facebook Toolkit or any other server
side solution to solve the problem. In this way, it meets
the rich client needs of the user.

Facebook can work in both the past and future versions of ASP.NET.
The great feature about the future with .NET
4.0 is that new client
side options for displaying data will come to light and make it easy for developers to work with
the JavaScript API. While 4.0 won't directly affect the Facebook API, it will make how you
use it easier and more

So now you've seen how Facebook integrates with an ASP.NET site, which does most of the work on the client.
We've mixed in a little jQuery to liven it up, too. But the core emphasis is on XFBML tags and the JavaScript API
getting the developer to know the building blocks in order to take the application to the next level. As more and more
people create Facebook profiles, a new era of key demographics may be at stake for your product or company,
making the Facebook APIs an

important addition to your developer toolkit.


For more information about Facebook, please see:

Developers site:

General Connect documentation:

XFBML tags:

JavaScript API Overview:

Complete JavaScript Reference: