IMPORTANT: Facebook announced that as of February 1, 2012 they are removing App Profile Pages, and the new way is pretty great. Read our article on the App Profile Pages being removed.
Updated Tutorial: Fall 2011
Facebook has been very busy updating how things are done, and one of the changes is how you create an iFrame application tab.
Although the concept is pretty much the same, the interface for creating a Facebook iFrame tab app has changed. This tutorial updates a tutorial we did on this subject earlier this year.
Related Tutorial: Add the Reveal Fan-gating Feature to your iFrame Page Tab
What is an iFrame application?
An iFrame application you allows you to embed an external Web page in your custom Facebook Page tab. Your “index” or “canvas” page is actually hosted on a non-Facebook server and is surrounded by Facebook “chrome” (the Facebook elements on the page).
Because this iframed page isn’t hosted on Facebook, it can use standard HTML, CSS, and JavaScript like any other Web page does. Interactions with Facebook content are done using the Facebook Software Development Kits (SDKs) and XFBML tags. (For this tutorial, the Facebook SDK is not required.)
The downside of this approach is that you need to be familiar with those technologies and you will need a Web-accessible server where you upload the files for your application page. Or you can add an iFrame-creation application to your page, such as TabPress, freeing you from having to create a Facebook application but more restrictive in that you can’t control the icon that appears next to the tab name in the left navigation.
Setting up your server
Facebook’s HTTPS / Secure Hosting Requirement
The first thing to know is that wherever you host the index page of your Facebook iFrame application, the server will have to be secure, i.e., have an SSL Security Certificate for the domain under which it’s hosted.
If your index page is not hosted on an SSL secure URL, or you don’t specify a Secure URL in your app settings, your tab will not display for those using Facebook under Secure Browsing. Instead, the user will see:
Read our article on Facebook Page Tabs and HTTPS.
The other assets called into your page (images, JavaScript, CSS, video, etc.) will also have to be hosted under HTTPS. We recommend Amazon S3 hosting for this, and this is also addressed in our HTTPS article.
Create your iFrame application
On your secure Web server, create a directory for your iFrame application. In this example, on our server we create a new directory called “facebook” and then a subdirectory called “mytestapp”. The file path will look something like this in your FTP program:
You will want to put all of your files (HTML, CSS, Javascript, PHP, etc) in the “mytestapp” folder or its subdirectories. If you don’t know how to do this, read this FTP tutorial.)
Your HTML file
Remember, in your HTML file you can utilize CSS — and inlining styles with the <style> … </style> tags works fine with iFramed HTML files — and JavaScript (Do not use FBML or FBJS!).
You’ll want to set the main container DIV for your content to 520 pixels wide. Here’s a very stripped-down example of your HTML file:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<link rel="stylesheet" type="text/css" href="style.css" />
<style type="text/css">
body {
width:520px;
margin:0; padding:0; border:0;
}
</style>
<meta http-equiv="Content-Type" content="text/html;
charset=iso-8859-1" />
</head>
<body>
<div id="container">
<p>This is some HTML content</p>
</div>
</body>
</html>
In the above example, I include both the code for an external stylesheet called with the <link /> tag, as well as inlined styles called with the <style> … </style> tags, in case you want to do it that way. Either should work fine.
Installing the Facebook Developer Application
The first step in creating an application in Facebok is to install the Facebook Developer application.
To do that, log in to Facebook and then visit the URL http://facebook.com/developers.
If this is the first time you’ve installed the Developer Application, you will see the Request for Permission dialog show below:
Click the Allow button to proceed.
Creating your iFrame application
Now that you have the Developer App installed, click on the Create New App button.
Give your application an “App Display Name” (the name displayed to users) and a “Namespace” (for use with Open Graph — 8-character minimum; alpha, dashes and underscores only — keep trying until you get a Namespace that hasn’t been used). Then tick the “I agree to Facebook Platform Policies” box; then click the Continue button.
On the next screen, enter the security phrase and then click Submit.
There are a lot of options you can tweak related to your application. In this post, we are going to focus on the basics needed to get your iFrame tab application up and running.
The Settings Tab
This is where you do the basic set up for your app.
First, at the top, you’ll see the App ID and App Secret values. Most frequently you’ll be using your App ID to integrate with Facebook.
Second, notice the “edit icon” below the App Secret. This is the icon that will appear to the left of your tab’s name in your page navigation, so make it eye catching and make the dimensions 16 x 16 pixels. If you don’t create your own icon, your tab will have a generic Facebook-tab icon: 
Basic info:
- App Display Name: Make this the same as the original value you provided;
- App Namespace: Make this the same as the original value you provided;
- Contact Email: Where you want Facebook to send emails regarding your app;
- App Domain: just put “mydomain.com” where “mydomain.com” is your secure hosting server;
- Category: Select a category from the pulldown list.
Cloud Services
Since Facebook instituted their HTTPS requirement for all applications, they started offering cloud hosting solutions for those who find setting up a hosting account and secure server too much bother, expense or both. But click the Learn More if you’re interested.
Select how your app integrates with Facebook
This is where you select the type of application you’re creating and how it integrates with Facebook.
An explaination of the Facebook-integration values
For the purposes of this tutorial, you will select “Page Tab” from the various integration options. It’s the last one listed but once you’ve saved your changes it will be listed first (as in the above example).
- Page Tab Name: The displayed name of the tab in the Page navigation;
- Page Tab URL: The unsecure URL (HTTP) of your index page — if the index page is named either “index.html” or “index.php” you can just put the directory with a trailing forward slash (as in my example above); OR you can specify a file name in the directory, eg myapp.html or myapp.php;
- Secure Page Tab URL: Same as the “Page Tab URL” but with HTTPS instead of HTTP;
- Page Tab Edit URL: You can create any URL at your domain here and then set up that URL to redirect to the Edit Page for the Facebook tab. This is commonly done using a 301 or 302 Redirect. I’m not covering 301/302 redirects in this tutorial;
If you intend to use calls to the Facebook JavaScript SDK on your tab – Add “App on Facebook” values
If you want to use the Facebook JavaScript SDK in your Page Tab — for example, our Share Button for Page Tabs — you will also need to select the “App on Facebook” integration, and add the same URL values as for “Page Tab”:
NOTE: The “App on Facebook” URL MUST be a directory, not a specific file:
http://www.myDomain.com/facebook/mytestapp/
NOT
http://www.myDomain.com/facebook/mytestapp/mycanvaspage.php
So if you need to specify an “App on Facebook” URL, you’ll need to use “index.html”, “index.htm” or “index.php” for the file name of your canvas page.
The “Canvas Page” value is autofilled by Facebook, with your Namespace value.
Click “Save Changes” and you’re done!
Installing your iFrame application on your Fan Page
UPDATE – December 9, 2011: Facebook is in the process of removing the App Profile Page completely, and has added new ways to add your App to your Fan Page. Read my article on Facebook’s removal of the App Profile Page.
If your App is only to add a Page Tab to your Facebook Page, and not an App that you want to make available to multiple pages, you can simply navigate to this URL in your browser:
https://www.facebook.com/dialog/pagetab?app_id=YOUR_APP_ID&next=YOUR_URL
Replace “YOUR_APP_ID” with your App ID and “YOUR_URL” with your App’s Canvas URL, both of which values are available in your app settings.
You’ll see a page similar to this the one below when you navigate to that URL:
After selecting the Page from the pulldown menu and clicking “Add Page Tab,” your iFrame app should now appear on your Fan Page. If you don’t see it there right away, you may need to adjust your Page settings. From your Fan Page, click on the “Edit Page” button in the top-right corner of your page. Then click on “Apps” and find the application that you just added. Click on the “Edit Settings” and you’ll get this popup dialog:
- Tab: If it says “Available (add)”, click “add” to add it to your navigation; if it says “Added (remove)”, you’re set;
- Custom Tab Name: You can override the default tab name by entering a new name in this field, up to 32 characters, and then clicking “Save”.
Click “Okay” to save your changes.
Troubleshooting
Based on feedback to this post, we are starting to compile some iFrame App Troubleshooting Tips. We will update this section as new questions some up.
Check your URLs!
Make sure that the URL you set for your iFrame is correct. Try accessing it directly, via your browser, instead of via your Page tab. Bad URL addresses are the most common problem. If the URL to the Web page or image you want in your iFrame Page tab is incorrect, obviously the tab won’t work.
You can also test the validity of your URL by right-clicking the area where your iFramed content should be and then select “This Frame: Open Frame in new window” or something similar (each browser presents this option a little differently).
Make sure you have specified an HTTPS / Secure URL for your Page Tab application. If you don’t, your tab won’t load for people using Facebook with Secure Browsing activated.
If you can’t add your Facebook Page Tab application to a Page
People often report this problem, and the cause will likely be one of the following:
- You’ve already added the App to your Page: Click the “Edit page” button at the top-right of your Page; then click “Apps” in the left column of the admin area; look for your Page Tab app; click “Edit settings” and make sure that in the popup dialog it says “Added (remove” and NOT “Available (add)”;
- You’re not an admin of the Page to which you want to add the App;
- Under the App’s “Settings > Advanced” area, you have set “Authentication > Sandbox Mode” to “enabled”; this restricts the ability to add the App to a Page to only the App’s developers;
- It’s a Facebook bug/glitch: Yes, this could be the cause.
Error messages from your server (error 405 – HTTP verb or similar)
If your server returns an error when Facebook tries to load the HTML page into the iFrame, you may need to change the file extension from .html to .php or .aspx (depending on the server platform you are using). When Facebook loads the iFrame, they do a POST to the index page in order to pass some data to your application and it looks like some servers are set up to not allow a POST to a file with the .html extension. We will be taking a look at how to access the data that Facebook passes in the next tutorial, but I wanted to mention this now since it caused issues for some people.
API Error Code: 191 Popup Dialog
If you get the “API Error Code: 191″ popup dialog error:
when using an embedded Share Button or other feature that requires the Facebook JavaScript SDK, it’s may be because you haven’t specified the “App on Facebook” URLs. See above for details.
Scroll Bars – Getting rid of them!
If your iFrame content causes a horizontal scroll bar to appear, something is causing the width to exceed 520 pixels, which is the maximum that Facebook allows. Read our tutorial on troubleshooting and eliminating the iFrame scrollbars.
We recommend adding some CSS (either inline as shown below or in your separate CSS file) to remove margin, padding, and border from elements by default. Many browsers add spacing around certain elements by default which can cause the scrollbars to appear unexpectedly.
<style type="text/css">
body {
width:520px;
margin:0; padding:0; border:0;
}
</style>
Next Steps
Up next: Creating a Reveal Tab on an Facebook iFrame application using the PHP SDK
We would love to hear what you would like to see in this series — If you would like to know how to do something specific using iFrame applications, just note it in the comments and we will see what we can do.
