Using the Force Toolkit for Facebook
Getting Started with Force.com for Facebook will require that you understand Facebook integration points and functionality as well as become familiar with Force.com development concepts. The purpose of this section will not be to walk you through all aspects of building an application with the toolkit, but rather to expose you to the provided functionality. You should have gone through the process of installing the toolkit into you developer org prior to this.
Some of the functionality will be appropriate for applications hosted entirely on the Force.com platform (social graph awareness inside your Force.com applicaition) while other functionality will be appropriate whether you application is specifically targeted at Facebook or Force.com. In addition, you have the choice of creating a Facebook iFrame application or a Facebook FBML application. Depending on the application requirements and implementation, you may choose one or the other.
For this tutorial we will simply be using a Visualforce page inside a developer edition account. Any developer edition account should be able to execute this tutorial.
Create a Facebook Application in Facebook
The first step is to create a new Facebook application from within Facebook. Assuming that you have already signed up to be a developer in Facebook, navigate to http://www.new.facebook.com/developers and click on the “Set Up New Application” button.
There are a few settings that need to be set so that you access the Facebook data. First off you will need to set the callback URL.
Enter the data for the first 3 fields. For the callback URL you must enter a URL similar to the one shown above. You must determine the pod your org is on and substitute your pod id (na1 in this case) for the one shown above. These are the only settings you need to make at this time. Save your changes.
Copy the generated API key from your new applications detail page. The API Key and your Secret are specific to you’re application and you will want to protect them so that no one else can impersonate your application. You will want to save this key as specified below.
The toolkit creates a new table in your org called FacebookAppList. This table has two custom fields, AppKey__c and AppSecret__c. You should create a new record for this table inserting the API Key into the AppKey__c field and the Secret into the AppSecret__c field. I would recommend setting the Name field of the record to the name of the application that you specified when you created your Facebook application.
You are now ready to try out the test page. Back in the Force.com website, enter /apex/FBToolkitPage after the salesforce.com part of the url in the address bar of your browser (https://na1.salesforce.com/apex/FBToolkitPage/?appName=MyApp). You should see something similar to the following:
Understanding the Page
Below is what the markup for the page looks like. If you use this basic template, you will be able to quickly and reliably be able to create Facebook apps on the Force.com platform.
The key item to be aware of is that you can use fbml tags directly in your page. To be able to do this you will need that div tag at the top to explicitly declare the Facebook namespace fb. These are the bits of magic that enable communication and authentication with the Facebook platform.
The composition tag is essentially a template for creating a Facebook aware page. You should not need to modify the page that is specified in the template attribute. Just wrap your content in this way and all the required Apex code and javascript code will be available to your page.
Closely related to the composition tag is the define tag. You should always place the define tag directly after the composition tag and name it "body". This tag tells the template where the "body" of your page is. The template has a corresponding insert tag <apex:insert name="body" /> that will put your page markup in the appropriate area of the template.
Finally, the tags that begin with c:. These are custom components that emit fbml tags. At this writing, I could not figure out how to include fbml tags directly on the page which led to this solution. Not every fbml tag is represented by a custom component, but they are easy to create and you can see how they are created by looking at their markup and controllers.
The controller for this page also presents a pattern to follow for Facebook applications. Below is the controller code for the test page.
<code>
public class FBToolkitPageController {
public FacebookApp__c fbc { get; set; }
public FacebookConnection fbConnection { get; set; }
public List<String> friendsList { get { return FacebookConnection.friendsList; } set; }
public FBToolkitPageController() {
if (FacebookConnection.fbApp != null) {
System.debug(LoggingLevel.INFO, FacebookConnection.fbApp.AppKey__c);
System.debug(LoggingLevel.INFO, FacebookConnection.fbApp.AppSecret__c);
System.debug(LoggingLevel.INFO, FacebookConnection.fbApp.FBUserId__c);
fbc = FacebookConnection.fbApp;
}
}
}
</code>
From the top. The first variable is a reference to the FacebookApp__c record. The FacebookApp__c record keeps track of Facebook visitors to your page. This record is created when the user authorizes the application. It provides useful information such as app secret, facebook user id, api key and a session key for API use. Any single user may have more than one record in this object, but should never have more than one record for any one Facebook app. In this way you can support multiple Facebook applications in a single Force.com org.
The FacebookConnection object is used to facilitate communcation of useful data between the template and your page. In particular, this is how you get to the FacebookApp object.
Your friends list, an important concept in social applications, is also kept in the FacebookConnection object. You make it available to your page by creating a local public property and retrieving the list from the FacebookConnection object. You should never instantiate the FacebookConnection object. It's properties and methods are static and it provides state for the duration of a request.
The contructor for the controller shown above is not necessary, but shows how you might access the data held by the FacebookConnection object.
A lot of the interaction that you will do with Facebook involves either your Facebook user id or your friend's Facebook user ids. So, even though it may not seem like alot, you have, with this simple implementation quite a bit of power at your finger tips.
Using the Test Page in Facebook
The preceding section showed how to bring Facebook data into your Force.com application. This section describes how to host the application on the Facebook platform. To do this you will take advantage of a new feature on the Force.com platform called Force.com Sites. Sites allows you to create a publicly facing, anonymously accessible we site backed by the full power of the Force.com platform. This is required to publish your application on Facebook.
For detailed information on creating a Force.com Site, please visit {link to doc}. Once you have your site created you will need to add some pages to the site. Add the FBToolkit page from the toolkit and make it the default page for you site. You also need to add a toolkit page called xd_receiver. This page is required to enable Facebook to communicate with your pages using javascript.
Once you have your site created create a new Facebook application as described above. There are a couple minor difference between the configuration for an application running entirely on the Force.com platform and one that is to be surfaced on the Facebook platform.
First, you need to change the callback URL for your application to indicate your new site domain URL. If the public URL to your site is "https://dave-developer-edition.na1.force.com", and your site is name "HiJinks", then you should set your callback URL to "https://dave-developer-edition.na1.force.com/HiHinks/". It is essential that you include the trailing slash. Leaving the trailing slash off will cause no end of heartache and debugging hours. Below the URL specification is a choice to indicate whether your application will be showed in an iFrame inside of Facebook or will generate FBML that is directly injected into Facebook. For this exercise select iFrame.
The next thing setting that you need to pay attention to is the Canvas URL. This is the URL that you specify so that users can find you application on Facebook. You can choose any valid URL that you like for this. The Facebook UI will let you know if the URL is available or not.
We also need to let Facebook know what kind of application this is. There are a few different types of applications. You will be creating a "Website", so you want to make sure that option is selected.
Finally, you need to allow your Facebook application to be added by a Facebook user. There are two settings that you need to make to do this. First, select Yes for the "Can your application be added on Facebook". This will cause the application configuration page to grow exposing the other option that you need to set. Scrolling down a bit on the page you will find a setting entitled "Who can add your application to their Facebook account?" and a checkbox next to the word "Users". Place a check mark in the check box and save the application settings.
To view your application click on the "View About Page" link on the application detail page. You will see the public "front door" to your application. You should see a link on the upper right part of the page to "Go to Application". Click this and you will see you application running in the Facebook platform!
You should see a link on the upper right part of the page to "Go to Application". Click this and you will see you application running in the Facebook platform!
The application in Facebook:
This is the most basic of functionality. With the toolkit you can create FBML applications, create feed stories, allow users to add the application to their profile, create info box data and more.