Getting Started with Facebook Connect
From Facebook Developer Wiki
Facebook Connect: The Basics of Facebook Development
Things every Facebook Connect developer should understand about programming with Facebook Platform.
Benefits
Congratulations on your decision to integrate your website with the largest network of people, friends, and family in the world! Facebook, with over 350 million users and growing, gives developers, businesses, and brands the tools they need to allow their website visitors and customers to, with only a few steps, easily share their website or brand with their friends and family.
Perhaps you need a way to virally spread your brand, product, or service. A recent study by Forrester Research stated that 83% of online consumers trust the opinion of a friend or acquaintance who has used a product or service more than any other source. Facebook Connect gives you this ability to have your users, visitors, and customers share your brand, product, or website with their own friends and acquaintances on a massive scale.
With Facebook Connect, you can tap into information about users, their friends, and what those users are doing with their friends. You can get your brand in the middle of their conversations, encouraging further conversation about your brand and helping them to spread it even further, in a seamless, transparent way that is non-intrusive to their friends.
With Facebook not only do you have the opportunity to share with hundreds of millions of users worldwide, but you are engaging with a very active audience as well. Almost half of Facebook users log in to Facebook at least once daily. Facebook users speak nearly 90 different languages, and over 70% of its user base lives outside of the United States. Over two-thirds of Facebook users have completed college.
Facebook provides you with the tools to access each and every one of these connections. With Facebook Connect you get a rich API into all this information, a simple markup language called XFBML which requires just a simple knowledge of HTML and JavaScript to integrate. Facebook provides you with a query language, enabling you to easily retrieve information about each user and their friends. Facebook even provides simple commenting tags and widgets to enable interaction on your site, and all this speaks back to Facebook.com, enabling your users to share even more of your content with their friends.
Facebook is your biggest ally towards sharing content quickly to existing and new audiences. With the single largest connected audience in the world, you have finally been given the power to leverage this network and strengthen your own brand in the process.
How It Works
So you've decided to integrate Facebook into your website, iPhone app, or desktop or Adobe AIR application, and you’re not quite sure where to begin. Understanding Facebook Connect and integrating the Facebook API into your website is as easy as knowing a few simple concepts. At a very basic level, it should take just 3 steps to have visitors of your website authenticating with Facebook.
First, you need to prepare your installation to communicate with Facebook -- You'll need to register your website with Facebook, and then install the file, xdreceiver.htm in the root folder of your website. xdreceiver.htm tells your website it’s okay for Facebook to set cookies and post data to authenticate the user on behalf of your website. This is simply so users never have to leave your website to authenticate with Facebook (except for a little popup Facebook generates the first time the user authenticates and authorizes your website to communicate with Facebook on their behalf).
Second, you copy basic JavaScript and XFBML tags onto your website in the place you want them -- Here is some sample code you can use - just copy this in place, changing your <html> line to contain the xmlns:fb part:
The first piece of code you need to insert onto your website is a call to the Facebook JavaScript client library, which does all the heavy lifting for you if you want to write your own JavaScript. With the methods in this library, you can do things like enable access to the XFBML markup language, allowing you to do things such as adding comments to your posts that communicate with your users’ Facebook feeds, generate Facebook authentication buttons, or just automatically display the current logged-in user’s Facebook profile image, or detect their name. These libraries also provide you all the tools you need to communicate with the Facebook API, with no need for any complicated development libraries on the back end.
Lastly, you write the Javascript code that gets executed after Facebook has confirmed the user is authenticated -- In the above code that would go in place of the “// Do something here...”. At this point you can continue to use the JavaScript client library to access the Facebook API, or use your own preferred development libraries to detect the user’s session and make calls on their behalf. That's it!
Concepts You Need to Understand
So far, this only covers the technical side of setting up a Facebook Connect-enabled website for your company, brand, or website. In order to understand the full breadth of what the Facebook API can provide to your website, you’ll want to understand some basic concepts first. This will also help turn the API into not just a development tool, but a powerful and useful marketing tool which requires little effort to deploy. The three basic concepts of any Facebook-enabled website that will help you fully grasp the Facebook Platform and what it can do for your website are:
- Identity
- Identity, of course, centers on the individual. Facebook provides powerful libraries enabling you to extract information very easily about each individual authenticated and authorized through your website, and their friends.
- The Graph
- A user's friends, or relationships and connections, are often referred to as the Social Graph. On Facebook, developers have full access to a user's friends and connections. This is what ties users together, and what enables you, as a developer, brand, or company to encourage your users to invite their Facebook friends to continue using your product.
- Sharing
- Facebook is about sharing. Everything you do on Facebook centers on sharing information between users and their friends. Facebook offers a set of powerful libraries in both JavaScript and your languages of choice, which allow websites to enable their users to share statuses, photos, videos, and even entire streams of data with their friends. Sharing is the content, often provided by your own website, that individuals are able to share with their Social Graph.
Social Widgets
If you don’t want to write any code or go through the process of full integration throughout your website, you can still integrate Facebook with your website by adding social widgets. A social widget is just a snippet of code given to you by Facebook or another provider, which you can copy and paste anywhere on your website.
Facebook provides two specific social widgets that you can copy and paste into your website. To set up a Facebook-provided widget, just go to the Facebook Connect Widget Wizard and follow the directions. This wizard will allow you to create either a Fan Box that integrates your Facebook Page with your website, or a Live Stream Box, enabling you to display all the statuses of Facebook users visiting your website. Or, with some simple copying and pasting of code and FBML, you can also embed a Comments Box on a blog or website which users can log in through Facebook and comment. If a widget is not sufficient, you may want to consider a plugin for your website or blog. There are multiple plugins available for platforms such as Movable Type and WordPress that can help you, in a matter of a few clicks, have your website or blog fully integrated with Facebook Connect. Be sure to check out the Facebook plugin directory for a list of what is available, or you can even create your own.
Implementation
In just a few steps, you can have all you need to know to get going with Facebook Platform.
Setting Up Your Website With Facebook
The steps of registering your website with Facebook Platform are simple. As we mentioned earlier it can be as simple as 3 steps to have your website up and running with Facebook! To get started you’ll need to install the Facebook Developer application and enter the information that Facebook needs to allow your servers to communicate with the API. Following that, you’ll need to install the xdreceiver.htm file on your servers, and then be sure the pages on your site using Facebook Platform are calling the Facebook JavaScript client libraries. Finally, you’ll need to write code that speaks with Facebook Platform. This can be as simple as a few XFBML tags, JavaScript client API calls, or passing information back and forth through AJAX and Facebook client libraries that reside on your own servers. To guide you through this process, you’ll want to be sure and read the Facebook Connect Set Up Guide.
The Run Around
To get you started, Facebook provides you with a fully functional website called the Run Around, written in PHP. Facebook made available the complete source and libraries you need to set up the application on your own servers.
If you need help, you may want to try and install this website on your servers and look at what it is doing, both on the front end with the JavaScript client library, or on your own servers with the server side PHP client libraries. This website provides you with a working application out of the box you can use to learn the ins and outs of Facebook Connect development. Be sure to look it over, download the provided source code (or get it from the Subversion repository), and play around with it yourself. Or just go to http://www.somethingtoputhere.com/therunaround/index.php which we’ve hosted on our own servers and try it out!
Speak Facebook in Your Own Programming Language
Facebook uses a REST-like interface to enable developers to communicate with the Platform. To understand REST, this simple diagram might help:
Basically, in REST, your website sends HTTP requests to Facebook’s servers, and Facebook returns data in XML format. In REST, depending on what type of HTTP call (GET, POST, PUT) and what types of information you request in the URL you send to the server, Facebook will return data that meets the parameters of the request.
There is a large amount of information on the API, but for the most part, that is all you need to know as a Facebook developer. Facebook provides a default set of libraries in PHP and JavaScript that do all the heavy work behind-the-scenes for you, allowing you to focus on the more important API methods. Also, Facebook provides libraries in ActionScript for Adobe AIR and Flash development, along with libraries specifically to help you integrate Facebook with your iPhone app.
In addition, third-party developers have written client libraries that speak REST with the Facebook API in just about any language you can imagine. There are libraries for Java, Perl, ASP, ColdFusion, Python, Android, and more. Or you can always write your own since it is all available via open protocols.
To get started, be sure to check out the list of libraries on the Facebook Developer Wiki. The basics of each call for most libraries will be the same as what you see in the API documentation (many of the libraries, including PHP, substitute the “.” you see there with an “_”). You’ll want to check the documentation for your preferred development library to see what you are capable of doing. Most of the development libraries are open source, so please contribute if you would like to see more!
Understanding Sessions: How to Get and Use Them
Getting a Session Through Authentication
To authenticate your users through Facebook, the user must both authenticate with Facebook, and approve your website to retrieve the types of information you’re requesting on behalf of the user. Once that takes place, Facebook sets a series of cookies, called the signature, proving to your app that the user has been authenticated. On Facebook Connect-enabled websites this is done via cookie. Facebook then runs a JavaScript callback which you have to set up in your code. This callback can run some more JavaScript, or call AJAX code on your servers, or even do a redirect to more code on your own servers which can detect the session.
Once this signature has been set, your app can make any call approved by the user. Your app will retrieve the signature from the cookies Facebook set at user authentication and it can then pass the signature as part of the API request back to Facebook, proving that your app is sending requests on behalf of a truly authenticated user. As we mentioned above, most of this is taken care of for you behind the scenes if you use one of the pre-written API client libraries for Facebook.
To get into the details of setting up a login button and making it work with the Facebook API, you’ll want to read the following articles:
Connecting the Session From JavaScript to Server-side Libraries
With a little bit of knowledge of AJAX, or even a simple JavaScript redirect, you can use your own server-side libraries to communicate with Facebook through Facebook Connect. The only thing you really need to use JavaScript for is the authentication of the user - after that you can either continue making calls through JavaScript, or pass the effort off to your own server-side client libraries to handle the rest.
To help you understand further, read Using Facebook Connect with Server-Side Libraries.
Detecting Session Errors
Users can have one of three states at any given time.
- They can be logged into Facebook and have authorized your app to make API calls on their behalf
- Users can be logged out of Facebook
- Users can logged in but have not authorized your app to make API calls on their behalf.
The first state is what you need to perform most API operations on behalf of the user.
Facebook provides the FB.Connect.get_status method to find out what state a user is in. At any time in your website, you can detect the status by calling FB.Connect.get_status, and it will return:
- FB.ConnectState.connected if the user is logged in and your app is authorized
- FB.ConnectState.userNotLoggedIn if the user is not logged in
- FB.ConnectState.appNotAuthorized of the user is connected but your app has not been authorized.
You can use the FB.init method to set specific callbacks which get executed when a user changes to different states. Be sure to read Detecting Connect Status to learn more about how you can detect a user’s session state at any time.
Why You May Want Your Session to Never Expire
Occasionally, you may want to perform actions on behalf of a user when the user is not explicitly logged into your website or Facebook. This may include actions such as sorting through a user’s information, sending out an email to your users through the Facebook API, and other tasks. This, and specific admin-related methods, are the only times you need to pass a private session key to your application (and these tasks can’t be performed with JavaScript client API calls since the user is not logged in when you perform these actions).
When you need to do such actions on behalf of your users, you need to prompt the user to grant you the offline_access extended permission. When you prompt the user for offline_access, a dialog appears, asking the user to approve the permission. If the user approves the action, you can then proceed to use that user’s session to process data on that user’s behalf, even when they aren’t logged in.
Be sure to read extended permissions in order to fully understand this. Your client library needs to pass the user’s signature with each call, so you’ll want to be sure to store the user’s signature in your database somewhere once you obtain the offline_access permission.
Understanding Sessions: Who Can See Your Users' Data?
As mentioned earlier, every Facebook user on your site exists in one of three states: logged in, not logged in, and not authorized. It’s important to know which state a user visiting your site is in (Are they the user? Are they a friend of the user? Are they not even logged in?) in order to determine what data to display to the user. Knowing such information can help you properly encourage your users to register or log in, or perhaps display more useful information if the user is visiting their own profile or data on your website. Also, this can be different if the user is viewing from the Web, an iPhone, or an Adobe AIR app.
We’ll leave it at that for now, but you’ll definitely want to read more about the various session states, and how to properly render data to each user depending on how that data is being used. To help you understand this further, please read Understanding User Data and Privacy.
Facebook Tools and Resources
Here are some essential tools every developer or Facebook Connect website owner should familiarize themselves with:
- The Developer Application
- The Facebook Developer application is your one-stop resource for all up-to-date news on the Facebook platform. In the Developer application we provide you with Platform Status Feed (also available via RSS), regular blog posts (also available via RSS), and useful links to the Developer Forum, documentation, and Facebook terms. It is here where you also configure and manage your Facebook Connect implementations, with links and powerful insights about each application or website you manage.
- Insights
- Insights are provided with each Facebook Connect integration on Facebook Platform. To get to them, just click on the application “more” link on the Developer app on Facebook, and click “statistics”. Insights provide you with powerful data about the Facebook users of your website. These include number of users, monthly active users, reasons why your app may be deemed “spammy”, along with powerful demographic data around the gender and age of your users.
- Blog and Status Feeds
- Facebook provides regular status updates via blogs and status feeds when we feel we have information that may be interesting or useful to you. Developers and application/website owners may find our developer blog or Platform status updates useful. There is also an official company blog you may find interesting. All important announcements go out on this blog, so it might be good for you to subscribe in your favorite RSS reader. Regardless, be sure to subscribe to all of these to have all the latest and greatest information about Platform.
- Facebook Developer Forum
- Have a question you just can’t find the answer to? You may want to try asking in the Developer Forum. In the forums, developers help one another out and often have been through the same problems you are experiencing. We believe in the practice of good Karma - if you ask a question and get good help from another developer, be sure to give back by helping out when you are able to with other developers in the Forum! Facebook also has one or two employees actively monitoring these forums, so you are likely to find an answer through this method.
- Facebook Developer Wiki
- This is where every developer should start. Familiarize yourself with where each type of documentation you need is. Get familiar with the XFBML documentation as a start, then move your way on to the API docs and get to know what you can do with Platform. Check out our useful tutorials and how-tos - there’s sure to be something helpful in your quest to learn more about Facebook Platform. If you can’t find what you want, but learn how something works elsewhere, feel free to add your own documentation. This is a wiki - it is built so our users can all contribute, in the way Social Networking was meant to be!
- Test Consoles
- The API Test Console and XFBML Console enables developers to post sample API calls or XFBML tags to see what gets returned, or how the output is rendered. Facebook also provides a Feed Template Console to help developers test how their posts will look in the activity stream of users.
- Setting Up Test Accounts
- Once you set up your website under your real Facebook account, you may want some users to run against your Facebook Connect integration. Sometimes you don’t want real users to know you have developed your app yet. For this reason, Facebook has provided you with the ability to create test Facebook accounts that you can test against your website, iPhone, or desktop application. To create a test account, simply go through the motions of creating a Facebook account, then, while logged into that account, go to http://www.facebook.com/developers/become_test_account.php.
- IMPORTANT! DO NOT CLICK ON THE LINK UNDER YOUR NORMAL FACEBOOK ACCOUNT OR YOUR CURRENT FACEBOOK ACCOUNT WILL NOT BE ABLE TO FUNCTION PROPERLY! Be sure to check out further details on test accounts.
Next Steps
Let’s get you started with just a very simple application. The Facebook Connect Tutorial will take you through each step necessary to create your very first Facebook Connect integration. Read through it, try it out on your own servers, and watch the video companion, and when you’re done you’ll have created your first Facebook Connect-integrated website!
Other things you may want to do when you’re done:
- Familiarize yourself with the XFBML docs
- Learn what the various API calls can do
- Learn more about the JavaScript Client Library and how to get started
Best Practices
Making Information Retrieval Easier with FQL
Facebook has the potential to send millions of users to your website or application in just a very short amount of time. For this reason, it’s good to do what you can to reduce the number of queries you make to the Facebook API. Each request costs both you and Facebook bandwidth, so Facebook provides a way to reduce the number of requests you have to make. When making large requests to the Facebook API for data, Facebook recommends you use their provided query language, FQL, to get specific sets of data from Platform.
A simple FQL query is sent via the API, enabling you to make with just one request what would normally cost you multiple requests to Facebook Platform. Here is a sample FQL statement:
You’ll want to get to know FQL and use it wherever possible to reduce headaches of having to change your architecture down the road. You can learn more about how to integrate FQL via the FQL section on the Developer Wiki.
Simplify Your Integration with XFBML
While developers are welcome to use their own styles, look, and feel, Facebook has a set look and feel which users are familiar with. Websites often get better response when users know it is Facebook providing the data, and not the website itself, for the components being integrated with Facebook Connect. In addition, Facebook can occasionally change the look and feel of their website and graphics, making it difficult to do this manually on a website. Occasionally you may just want to simplify your development, reducing the amount of JavaScript and/or back end code you need to generate to do a specific task.
For these reasons, Facebook has provided XFBML to simplify the development process. XFBML is simply a derivative of FBML, built to work with Facebook Connect-enabled websites. XFBML is a series of tags you can use, which represent snippets of HTML code, and do much of the work for you that would often require several API calls and back end code references to generate. Facebook simplifies this process for you, and makes it so at a very basic level, you don’t need to know any fancy JavaScript or high level language skills to begin building your Facebook Connect integration.
Be sure to review the XFBML documentation for Facebook Connect to see what you can do to shorten your development load.
Appendix
Reference Docs
- Facebook Developer site
- Facebook Developer Wiki
- Facebook Connect documentation
- XFBML documentation
- FQL documentation
- Facebook API documentation
- Facebook JavaScript Client Library documentation
Policies and Terms
To ensure Facebook remains a safe and comfortable place for users and developers alike, Facebook has established a series of Platform Principles and Policies every developer must adhere to. Please be sure to read through this carefully - you do not want to have to re-write your application because of a violation of the terms! Facebook assumes every developer has agreed to this when they first configure their website, iPhone app, or desktop application.
Questions?
For those with questions or issues while developing their Facebook Connect integrations, Facebook has provided the following resources, which should enable you to get all the information you need should a problem arise. We recommend searching through our documentation before asking, but these resources are always available and at your disposal:
- Facebook Developer Forum
- IRC
- Developer help form (also found at the top of the Developer app)
Other Tutorials
Goldstein Technologies has put together a tutorial showing how to integrate Facebook Connect into an existing site. It covers topics like how to link up your existing site users to their Facebook identities and more.
