Connect/Implementing Profile Boxes
From Facebook Developer Wiki
Contents |
Implementation
Setting up your own profile box is easy! To get you started, let’s give a little background about the architecture, and how a profile box eventually gets rendered on a user’s profile.
Understanding the Architecture of a Profile Box
Understanding the architecture behind profile boxes can help you understand how to design your profile box. This diagram may help:

To sum up the diagram:
Before the user clicks the “add to profile” button, your website sends (from your servers) static FBML to Facebook via the profile.setFBML API call.
When a user visits a profile, Facebook takes that content and displays it to the user. Content, with the exception of FBML tags, is static for the user at this point.
Optionally, a user may click a button within your profile box, and at that point, via AJAX and FBJS, your profile box may become dynamic. All content before that point must be generated prior to sending it to Facebook via the profile.setFBML API call.
You may refresh this content any time by calling profile.setFBML again.
Note that the user profile never sends a request back to the website’s servers. With the exception of AJAX calls (after an onClick-type event), the user profile box content is static once it leaves your servers.
Creating Your Profile Box
Creating the Box
To create your profile box, you’ll need to know some simple FBML, and then be able to make calls via the Facebook API.
Now, you need to create the box, and send it to Facebook. You can do that any time during, or outside the user’s active session (again, using your own infinite session key). Creating the box requires just 3 steps:
1) Write the FBML for your Box’s Wall Tab View
This can be simple HTML (so long as it fits in the FBML Guidelines), or complex FBML and FBJS. Keep in mind that a user must click via an onClick or similar explicit action before any of your JavaScript will execute! You’ll also want to include an fb:subtitle tag if necessary. Be sure to include FBML for each type of user visiting the user’s profile, as we specified earlier!
2) Write the FBML for your Box’s Boxes Tab View
Everything in step 1 applies here, but you’ll also want to be sure to include an fb:narrow and fb:wide view in case the user moves your box from one column of the Boxes tab to another.
3) Send Your FBML to Facebook!
Once you have your Wall tab view and your Boxes tab view, you send the box to Facebook simply by calling profile.setFBML, including FBML for each of the views in the call. In PHP, your call would look something like this:
Now, the user just needs to add the profile box you just created to his or her profile. We’ll explain that next.
Enabling Users to Add the Profile Box
Before the profile box you create for your website ever shows up on a user’s profile, the user must tell Facebook to put it there. It’s your responsibility to prompt the user on your website to add this profile box. You do that with some simple XFBML - the fb:serverfbml tag, and including within the tag a call to the fb:if-section-not-added and fb:add-section-button FBML tags. Your XFBML will look something like this:
Your “Add to Profile” box will look something like this:
Updating the Profile Box
To update your profile box at any time, simply call profile.setFBML again with updated FBML, and the box will be updated for the user you specify.
Best Practices
Creating a Well-designed Profile Box
As we mentioned earlier, the profile box is intended as a means of identity for your users on Facebook. Therefore, it can be a great way to allow your users to show off what they have done recently on your site. Some best practices in designing your profile box include:
- Focus on identity - what are the interesting things a user has done on your site that they would want to share with their friends?
- Do what you can to blend in with the current Facebook look and feel, while retaining your brand identity and respecting Facebook’s own copyright.
- Include latest activity taken on your site - for instance, SocialToo.com lists the latest SocialSurveys their users have taken. Digg.com could list the latest Diggs of a particular user.
- Give all users the opportunity to learn more about the website, but such links must be non-intrusive and should avoid deception.
Policies
The main policy to remember when creating your Facebook profile box is that the profile box is there for the user to represent their activity in your application or website, not for you to promote your website. Also, you can not advertise or monetize your site in any way in a profile box on user profiles. In addition, there should be no incentive of any type to encourage users to add your profile box to their profile box beyond the opportunity to share more information about themselves.
It’s always a good idea to review the Platform Principles and Policies to be sure you are staying in compliance.
