If you’re NOT on the HyperArts Blog, CLICK HERE!
IMPORTANT: You have to upgrade your Fan Page to the new layout before the application below will work on your Fan Page. Many Pages will see a big banner at the top of their Page announcing the upgrade. If you don’t, you can click here to upgrade your Fan Page.
In our previous tutorial on Facebook iFrame tab applications, we looked at how to set custom iFrame tabs on your Facebook Fan Page.
In this tutorial, we will look at how you can use the information that Facebook passes to your iFrame application when it is loaded to customize the experience of the person viewing the tab. This includes presenting different content for fans vs. non-fans, aka the Reveal tab or Fan-gating.
NOTE: A basic understanding of PHP is required
This tutorial will require that you have at least a basic understanding of PHP. If you do not, you can certainly copy the code from this tutorial and use it, but it may be difficult for you to modify the code for your exact needs. We cannot provide support for PHP issues that you may experience since they are outside the scope of this blog.
There are lots of great resources about PHP on the Internet that can help get you up to speed. I have found the resources at Tizag to be useful as I learned PHP, so you might check them out.
Facebook’s new iFrame Page Tabs — the signed_request variable
When a Facebook user clicks on your “tab” in the left-column navigation, Facebook loads your page via an iFrame, which embeds your content into the Facebook page. While Facebook is loading your page, it POSTs some information about your page to your application index page.
The information that is POSTed is contained in an encoded variable called “signed_request”. When you decode the signed_request via PHP, the following information will be able to you:
- The Page ID for the tab that is loading your application;
- Whether the logged-in user has “liked” this Page;
- Whether the logged-in user is an admin of the Page;
- The country of the user;
- The locale of the user.
Decoding signed_request data with Facebook’s PHP SDK
In this article we will be looking at how to handle the decoding of the signed_request data using the Facebook PHP Software Developer Kit (SDK) . If your server doesn’t support PHP, you may be able to accomplish something similar using the JavaScript SDK, but that is beyond the scope of this blog post.
Installing the Facebook PHP SDK
You can download the latest Facebook PHP SDK here. Once you have downloaded the file, unzip it (if your OS didn’t already). The file that we need is in the “src” directory and is called “facebook.php”. We recommend that you put this file on your server in the same directory your index file resides.
Loading the Facebook PHP SDK in your index file
Next, you need to tell PHP to load the Facebook SDK file when your index file is loaded.
Open your index.php and add this PHP code:
<? require 'facebook.php';
Note: If you called your index file “index.html” based on our earlier iFrame Page Tab tutorial, you will need to change the name to “index.php” and also change the file name in your Facebook Application settings (Facebook Integration > Page Tabs > Tab URL).
Initializing the Facebook PHP SDK
Next, you will need to initialize the PHP SDK. To do this, insert some additional code into your PHP:
$app_id = "APP_ID_HERE";
$app_secret = "APP_SECRET_HERE";
$facebook = new Facebook(array(
'appId' => $app_id,
'secret' => $app_secret,
'cookie' => true
));
Note: You will need to replace the “app_id” and “app_secret” values with the ones for your application. You can get these by going to facebook.com/developers. Under “My Apps” on the right side of the screen, click on the name of your application. You will see the App ID and App Secret values as shown below.
Using the PHP SDK to decode the signed_request variable
We are finally ready to decode the signed_request variable that Facebook POSTs to your application.
$signed_request = $facebook->getSignedRequest();
We can now access specific values in the array like this:
$page_id = $signed_request["page"]["id"];
$page_admin = $signed_request["page"]["admin"];
$like_status = $signed_request["page"]["liked"];
$country = $signed_request["user"]["country"];
$locale = $signed_request["user"]["locale"];
You might want to add some “echo” code to display the values of each setting for troubleshooting:
echo "<br>page id = $page_id";
echo "<br>page admin = $page_admin";
echo "<br>like status = $like_status";
echo "<br>country = $country";
echo "<br>locale = $locale";
Using the signed_request variables to create the Reveal / Fan-gating feature
Now comes the fun part. The most common thing you might want to do is present different content to people who have “liked” your page vs. people who have not yet liked it.
You can use the variables in signed_request to check if the visitor has liked the Page on which your iFrame tab resides. You do this by testing the value of the variable “like_status”:
if ($like_status) {
echo "You like us";
}
else {
echo "You don't like us yet";
}
Create Page Tab content based on which Fan Page the app is installed
Another common use of these variables will likely be to customize an application based on which Fan Page it is installed on. This will allow you to use a single application on multiple Pages by tailoring the output to a specific Page.
You can test the Page ID like this:
if ($page_id == '12345') {
echo "content for 12344";
}
elseif ($page_id == '56789') {
echo "content for 56789";
}
You can do similar tests to customize the content based on country or locale or to display specific content only for Page Admins.
Can I access user data?
Facebook does not pass any personal information about the logged in user to your application unless they have specifically authorized your application. If they have authorized your application, their User ID will be passed as part of the signed_request and you can access it in the same way that we accessed the other values above. Creating the Request for Permissions dialog is beyond the scope of this tutorial, but we might cover that in a future tutorial if there is interest. Once you have the user ID, you will be able to access whatever information the user gave you access to via the Graph API.
Download the code
We have created a ZIP file with the sample code from this tutorial as well as the latest version of the PHP SDK file (facebook.php). You can download it here.
Troubleshooting
We will update this section with iFrame app troubleshooting apps as the discussion continues in the comments.
Check your protocol (HTTP vs HTTPS)
There is a known issue where iFrame applications contained on Fan Page Tabs appear blank when accessed over SSL (via a URL that begins with https:// rather than http://). This normally happens when a FB user turns the setting at Account Settings > Account Security > Secure Browsing (https) on. It can also happen if you the user goes to https://facebook.com rater than http://facebook.com. The expected behavior is that users accessing the tab over https should see the page listed in the Secure Canvas URL in the Application Setup. The bug is that the page is just blank instead. You can read more, and vote for, the bug at http://bugs.developers.facebook.net/show_bug.cgi?id=15200
iFrame content not visible when you are not logged in to Facebook
There was a known Facebook bug that sometimes caused iFrame app tabs to appear blank when the visitor is not logged into Facebook.
Update: 3/1/11 Most reports seem to indicate that this bug is now resolved in production.
The Facebook SDK requires PHP 5
In order to use the PHP SDK (aka facebook.php), you will need to have PHP5 installed on your server. If you are not sure what version of PHP you have, put this in an empty index.php file:
<? phpinfo() ?>
Check your URL’s for www
Some servers are set to redirect “domainname.com” to “www.domainname.com”. If you server does this and you specify “domainname.com” in your Canvas URL in App Setup, the redirection will erase the signed_request parameter and all of your variables will be blank. To get around this, just include the “www” in the Canvas URL. See our previous tutorial for help on application setup.
Next Steps
This is just a hint of the powerful new things you will be able to do with iFrame apps on your Fan Page. We hope that you find this useful — we would love to hear about what topics you would like to see covered in future posts in this tutorial series. Just add a comment to the post to let us know!
