Creating a Platform Application

From Facebook Developer Wiki

Jump to: navigation, search

This guide shows you how to configure the settings and integration points for a Facebook Platform application and configure your host server. It does not discuss the actual development of your application. You can find the code for some sample applications on the Facebook Developer website. You can create an application in minutes using the code for a basic Facebook application in the Developer application (follow the example code link).

Follow the sections in this guide to create a Facebook application. The essential steps are:

  • Preparing yourself and your server.
  • Adding the Facebook Developer application to your Facebook account.
  • Setting up your application on Facebook.
  • Developing your application (beyond the scope of this document).
  • Managing your application.

Contents

Knowing What Tools You Need

You can develop your Facebook application in whichever development environment you prefer. Facebook and other third party application developers have created client libraries for these environments.

Facebook supports PHP and JavaScript client libraries. You can download the PHP libraries at http://svn.facebook.com/svnroot/platform/clients/packages/facebook-platform.tar.gz. For information on where to download libraries provided by the Facebook community, see Client Libraries.

Once you set up your environment, you need to prepare the server that will host your Facebook application.

Setting Up Your Server

In order for your application to work correctly with Facebook, you need to take the following steps to prepare your server.

  1. Verify that your server can serve an HTML file. That is, make sure you can view a file in a browser on a different computer than your server.
  2. Upload the appropriate Facebook client library to your server. See above for more information.
    For example, if you are developing your application with PHP, its client libraries are available at http://svn.facebook.com/svnroot/platform/clients/packages/facebook-platform.tar.gz. Untar the archive then upload the PHP files to your server. You need to include these files in your PHP code.
  3. If your application stores user or application information in a database, install a database such as MySQL on your server. For more information on MySQL, see the MySQL website: http://dev.mysql.com/doc/mysql/en/index.html.
  4. Verify that you can write a database program outside of Facebook Platform.

In addition, you should make sure cURL works on your server and is enabled. For more information, see bug 4164.

In the meantime, you can take a look at some demo applications.

Adding the Facebook Developer Application

To add the Facebook Developer application, go to http://www.facebook.com/developers and click Add Developer. Once you add the Developer application, the My Applications page appears. This page contains links for downloading the client libraries and a sample application. With Facebook's Developer application, you can:

  • Request up to 100 API keys, customize your application settings, and create and manage the applications you have developed from right inside Facebook.
  • Connect with the developer community through the discussion boards and find local developer events.
  • Find the reference material you need, including links to client libraries, sample code and sample applications, to help get you started.
  • Check out the Facebook Platform Developer Blog (at http://developers.facebook.com/news.php?blog=1&format=xml) for the latest news on upcoming features and events, and the Facebook Platform Status Feed (at http://www.facebook.com/feeds/api_messages.php) for the current status of Facebook Platform. You can subscribe to these RSS feeds for the most up-to-date information.

Creating Your Facebook Application

Once you've added the Facebook Developer application to your account, you can begin creating your first application for Facebook.

Coding aside, creating an application takes just a few minutes.

You should define the integration points for your application once a user has added it to his/her Facebook account. The more integration points you utilize, the deeper your application is immersed into Facebook. If you're unfamiliar with Facebook integration points, you should read Anatomy of a Facebook App to get an idea as to how you can integrate your application into the Facebook experience.

  1. From the Facebook Developer application's home page, click +Set Up New Application. The Create Application page appears. Enter a name for your application in the Application Name field. The name cannot be longer than 50 characters and cannot contain any of the words "face", "poke", or "wall", or be similar in name to any Facebook application (like Wall, Photos, and so forth).
  2. Follow the Terms of Service link and read the Facebook Platform Terms of Service. Go back then select Agree to confirm that you agree to the terms.
  3. Click Save Changes to save these settings and continue configuring your application.

Click the appropriate tab to configure those settings (for user profile, Facebook Connect, and so forth). At any point, you can either save your settings (click Save Changes ) or continue configuring them as needed.

Configuring Basic Settings

Basic settings include essential elements of your application, like its application ID, API key and secret. You'll use these setting in various parts of your code, so make note of them.

  1. You should provide a description of your application in the Description field. The description appears along with your application name in the application directory and when a user is adding your application. The description should explain what your application does and cannot be longer than 250 characters. You cannot use FBML in your description.
  2. It's a good idea to add an icon for your application. This icon appears in the Applications menu and in the Allow Access screen. The icon must be 16 by 16 pixels. Click Change your icon and browse for one.
    Note: Your application icons appear on off-white backgrounds on Facebook. We strongly recommend that, if you're not already doing so, you use transparent GIFs for your icons. For most applications, this should be as easy as adding transparency to the edges of the icon.
  3. You can include a logo for your application that appears in the Application Directory and on the Requests page. Next to Logo, click Change your logo and browse to an image file. The logo can be up to 75 x 75 pixels, and must be in JPG, GIF, or PNG format.
  4. If your application is in a language other than English, select the language in the Language list. If you plan on internationalizing your application, you should use English as the native language at this time, as the Translations tool can translate from English only.
  5. If there are other developers working on this application with you, enter their names in the Developers field. They can modify your application. They must be your friends before you can add them here.
  6. You need to provide an email address in the Developer Contact E-mail field. Facebook uses this address if it needs to contact you about your application. This address can be seen only by Facebook staff. Facebook populates this field automatically with the email address tied to your Facebook profile, but you can use a different address if you so choose.
  7. You need to provide a way for your users to contact you. They can do so via an email address or a form on a page on your site.
    • If you want your users to contact you via email, select Email next to User Support Address and enter an email address in the field below. Any messages your users send from your application's help page are sent to this address. Facebook populates this field automatically with the email address tied to your Facebook profile, but you can use a different address if you so choose.
    • If you want your users to contact you via a form on a page on your site, select URL next to User Support Address and enter a URL to a help page on your site in the field below.
  8. It's valuable to your application's users if you provide them with a help page. Enter the URL to your application's help page in the Help URL field.
  9. If users can set any privacy settings for your application, specify the URL to the settings in the Privacy URL field.
  10. Enter the URL to your application's terms of service in the Terms of Service URL field. Any user authorizing your application must accept your terms of service first.

Configuring Authentication Settings

  1. You need to decide who can use your application. If you want users to be able to use it, check the Users check box. If you want Facebook Pages to add your application, check the Facebook Pages check box.
  2. You should specify a URL in the Post-Authorize Callback URL field. When a user authorizes your application, Facebook sends a notification to this URL. This URL cannot be a page on Facebook (like your canvas page), and cannot be longer than 100 characters.
  3. You need to write server-side code to log or handle what happens when a user removes your application. You should provide a URL to a notification page in the Post-Remove Callback URL field. This URL is called after a user removes your application from his or her profile. Facebook sends an automated POST call containing the variable fb_sig_user (user id). This URL cannot be that application's canvas page or a Facebook-framed page, because removing an application means the user is no longer using it within Facebook. The user does not see any content you display in this page.

Configuring Profile Settings

  1. If your application has a profile tab, enter the default name for the tab in the Tab Name field. The tab name can be up to 11 characters. Users can change the application tab name.
  2. If your application has a profile tab, enter the URL to the tab's contents in the Tab URL field. This URL must be relative to your canvas page URL.
  3. Choose whether your application's profile box appears in the narrow or wide column on the Boxes tab when the user first adds the box to his or her profile. Select either the Wide or Narrow Default Column option. After a user adds the profile box, you can set FBML that appears here.
  4. If your application has an info section, enter an Information Update Callback URL where Facebook can notify you when a user's Info tab data changes.
  5. If your application is integrated with the Publisher, specify the action (the label for the Publisher button) in the Publish Text field and callback URL (from which the Publisher can fetch the content to display) in the Publish Callback URL field when publishing content to friends.
  6. If your application is integrated with the Publisher, specify the action (the label for the Publisher button) in the Self-Publish Text field and callback URL (from which the Publisher can fetch the content to display) in the Self-Publish Callback URL field when publishing content to the user's own profile.
  7. If you want a Facebook Page admin to be able to edit your application (say to add more content to the Page with it), enter the URL in the Edit URL field. The URL cannot be longer than 100 characters.

Configuring Canvas Page Settings

Your application's canvas page is where your application lives on Facebook.

  1. Enter the name at which you'd like your application to be hosted inside Facebook in the Canvas Page URL field, omitting any spaces. Facebook recommends that you use your application name or something similar for this URL. The canvas page name must be unique, must be between 7 and 20 characters (inclusive), and can contain only letters, dashes, and underscores.
    The canvas page URL provides a way for an application to live inside the Facebook frame, although Facebook doesn't actually host the third-party content (except for some caching of images to assist with performance). Canvas pages are surrounded by the Facebook frame, and any application content requested within the canvas page URL get served out of the callback URL.
    The canvas page is also where FBML gets rendered. FBML does not get rendered on your server; it only gets rendered within Facebook.
    For example, if your callback URL is example.com/ and your canvas page URL is apps.facebook.com/pokewall/, then apps.facebook.com/pokewall/poke.php requests example.com/poke.php. If your canvas page uses a .PHP file extension, and you intend to have other files in the same directory as the canvas page, you must add ? to the end of the canvas page name (for example, poke.php?). Otherwise, you should put other files in a separate directory.
    Note: At this time, canvas page URLs must be all lowercase. For more information, see bug 3959.
  2. In the Canvas Callback URL field, enter the URL of the directory on your server where you plan to create your application. The canvas callback URL serves the content for your canvas page (the home page for your application) to Facebook. The canvas callback URL cannot be longer than 100 characters.
  3. You should provide a Bookmark URL so a user can easily bookmark your application, and thus have it appear on the user's Applications menu. Enter your canvas page URL in the Bookmark URL field. For example, if your canvas name is acmeenterprises, your Bookmark URL must be apps.facebook.com/acmeenterprises/.
  4. You should specify a URL in the Post-Authorize Redirect URL field. When a user authorizes your application, that user is redirected to this URL. Typically, you want to make this URL your canvas page URL, so that the user sees your application right after he or she adds it. The URL cannot be longer than 100 characters.
  5. You need to specify how your canvas page gets rendered on Facebook. If you are using FBML to render your canvas page, select the FBML radio button. If you are not using FBML and plan to use your servers to render your canvas page, select the IFrame radio button. Your canvas page is rendered in an inline frame in the user's profile.
    If you are using FBML in your canvas page, Facebook's servers render the content of your application before presenting it to the user.
    To understand the differences between FBML and iframe applications, read Choosing between an FBML or IFrame Application.
  6. If your application gets rendered in an iframe, decide whether you want the iframe to be smartly sized or resizable and choose the appropriate IFrame Size radio button. A smartsized canvas page iframe fits the remaining space on the page when it loads, but the application cannot change the size of the iframe in case the content changes size. For more information, see Resizable IFrame and fb:iframe.
  7. If your canvas is designed for the Facebook profile before July 2008 and you want the canvas page to use the full width of the wider canvas page on the current profile (760px), check Use full canvas width. Otherwise, select Old width (646px).
  8. If you want to improve the speed with which your canvas pages load, you can turn on the Quick Transitions feature.

Configuring Facebook Connect Settings

You should configure the following settings only if this API key is for a Facebook Connect site.

  1. You must specify a Connect URL, which is the primary URL to your Facebook Connect site.
  2. You should include a logo that appears on the Facebook Connect dialog. Next to Facebook Connect Logo, click Change your logo and browse to an image file. The logo can be up to 99 pixels wide by 22 pixels tall, and must be in JPG, GIF, or PNG format.
  3. You can offer your users a link to their account on your site, which appears on the Requests page on Facebook in response to a Connect request from another friend on your site. In the Account Preview URL field, enter the URL to your site where a user's account would appear. Facebook appends the user's email hash and name to the URL.
  4. If your site is going to implement Facebook Connect across a number of subdomains of your site (for example, foo.example.com and bar.example.com), you need to enter a Base Domain (which would be example.com in this case). Specifying a base domain allows you to make calls using the PHP and JavaScript client libraries as well as get and store session information for any subdomain of the base domain. For more information about subdomains, see Supporting Subdomains In Facebook Connect.
  5. You can specify an Account Reclamation URL to give a user who deactivates his or her Facebook account the option to set up an account specific to your site. For more information, see Reclaiming Accounts.
  6. If your Facebook Connect site uses the Friend Linking feature, you can request this ability from Facebook. Select Request then state how your site uses friend linking in the box below. The request is sent to an automated queue at Facebook, and it may take a few weeks before Facebook lets you access the feature.
  7. If your Facebook Connect site uses a contact importer or some other mechanism to let your users search for other users on your site, select Yes next to Native Friend Linking then explain the process in the box below. Provide a URL to any supporting documentation if you can.
  8. If your Facebook Connect site is going to publish the actions your users take back on Facebook, you need to create at least one template bundle in the Feed Template Console. You need to create a template only for one line and short stories.
    1. Once you create a template there, make note of its bundle ID and enter that ID in the Template Bundle ID field.
    2. Describe the story in the Story Description field.
    3. List out any custom tokens in the Template Tokens field and the values with which you want the tokens to be replaced.
    4. Click Add Template Bundle to associate this bundle with your Facebook Connect site.

Configuring Widget Settings

If you are using a social widget like the Comments Box, you need to specify some settings on the Widgets tab.

  1. In the Administrators box, enter the names of any Facebook friends who you want as administrators of your social widget. The administrator of the Comments Box, for example, can delete any comments directly or on Facebook. Only a developer of your application can add administrators and moderators.
  2. In the Moderators box, enter the names of any Facebook friends who you want as moderators of your social widget.
  3. If you want to be notified whenever someone adds content to the social widget, check Include me.
  4. You can set global permissions for your social widget. Decide whether you want a blacklist or a whitelist for viewing content. In blacklist mode, any users you specify cannot see the content of the social widget. In whitelist mode, only the users you specify can see the content of the social widget. You can also allow anonymous comments, so users without Facebook accounts can comment by including a name and email address.

Configuring Advanced Settings

You can accept the defaults for the following settings. Change them only if you must.

  1. If your application is going to run in a user's Web browser, select Web for Application Type. Otherwise, if the application is going to be downloaded to your user's desktop and run from there, select Desktop. For more information about creating a desktop application, consult the Desktop Application guide.
  2. If you want to restrict your application so that only the developers you specified earlier can add it for testing purposes, enable Sandbox Mode. You can add more developers yourself when you edit your application; these developers must be your friends before you can add them.
  3. If you want Facebook to integrate your application so that it can be used on a user's mobile device, enable SMS Integration. Facebook provides additional functionality for applications that run on mobile devices.
  4. If you are building a Facebook Connect for iPhone app, you can promote your iPhone app in the stream by adding your iPhone Application ID. Users of the Facebook for iPhone app will see a link to your app in stream stories posted by your iPhone app, allowing the user to download your app from the iTunes App Store.
  5. If your application can create a message attachment, in the Attachment Text field, specify the text for the action. This text label appears in your application's drop-down list or on the button that initiates the action. The label cannot be more than 20 characters.
  6. If your application sends message attachments, in the Attachment Callback URL field, enter the callback URL on your server where you store the attachment content.
  7. If your application is Web-based, in the Server Whitelist field, you can enter the IP addresses of your servers that can access Facebook's servers and serve information to your application. For multiple IP addresses, separate each address with a comma. Facebook rejects any requests for your application from IP addresses other than those you listed.
    Important: If you are configuring an IFrame application, Facebook Connect site, or Facebook Connect for iPhone application, and you whitelist your servers, you must enable the Session Secret Whitelist Exception (see the next step).
    This is useful for security, as it prevents other applications from impersonating yours if they steal your secret key. However, it also prevents you from testing your application through localhost.
  8. If you are using a server whitelist, select Enable to allow IFrame applications, Facebook Connect sites, and Facebook Connect for iPhone applications to bypass the whitelist (so you can make calls to the JavaScript Client Library, or if your application uses a session-based temporary secret.
  9. Select Yes only if your application or site publishes Feed stories involving video sales, rentals, or subscriptions. Your site must conform to the Video Privacy Protection Act.

Authorizing Your Application

Once you've created your application, make sure you authorize it for your profile. This way, you can verify that users can access your application.

  1. To add your application, either click on it in the My Applications box in the Developer application page or click View My About Page on the My Applications page.
  2. Click Go to this Application. This takes you to a standard page for adding an application.
  3. Click Allow.
  4. Verify that you are redirected to your canvas page (or wherever the post-authorization redirect URL takes you). Bookmark your application so that it appears in the Applications menu on your profile.

Submitting Your Application to the Facebook Application Directory

Once you have finished creating, configuring and developing your application, you can submit your application to Facebook. Submitting an application adds it to the Application Directory. This allows users to see your application when searching or browsing the Application Directory. You are not required to submit your application to the directory; it is simply one way for you to showcase your application. Before you submit your application, it must meet the following requirements:

  • It must have at least 5 users who've authorized your application or 10 monthly active users (MAU)
  • Its name cannot contain word “face”
  • It has a canvas page URL
  • You provided an application description and logo

To submit your application, do the following.

  1. Select the Facebook Developer application and under My Applications, click See My Apps. The My Applications page appears.
  2. To the right of the application you want to add, click Submit Application. On the submit page, your application's name and, if they were specified, your support email address and application description all appear in their respective fields.
  3. If you want, you can change the developer contact email address or the description before submitting.
  4. If your application can be used on a mobile device, check the Mobile Integration check box.
  5. You can add a logo that represents your application in the Application Directory. Click Change your logo and browse to an appropriate image file. The image can be a GIF, JPG, or PNG no larger than 75 by 75 pixels.
  6. Click Save to submit your application.

There is still one more step you should take to make your application easier for users to find. You should edit your application's About page to categorize your application. See the next section for more information.

Managing Your Applications

You can manage all of your Facebook applications from the My Applications page of the Developer application. You can modify any settings, URLs and other elements of your applications. In addition you can view basic information and statistics about your applications and delete applications if you desire. The My Applications page displays the following information for each of your applications:

  • Its public API key. This key is generated by Facebook when you create the application. Enter this key into the appinclude.php file you create.
  • Its secret API key. This key is generated by Facebook when you create the application. Enter this key into the appinclude.php file you create.
  • Your support and contact email addresses.
  • Its callback URL.

Creating a New Application

You can create a new application from the My Applications page. Click Apply for another key. The New Application page appears, and you can create a new application as discussed earlier.

Viewing Your Application's About Page

Your application's About page contains information about the application that users see such as number of active daily users, reviews and discussion boards, which of a user's friends have added the application and information about the developers. It's also the place where you can categorize your application so it shows up in the appropriate areas of the Application Directory when a user browses for applications. Users can also report or block your application from here.

To view the About page, go to the My Applications page and click View About Page.

Editing Your Application's About Page

You can modify your application's name, its description, the two categories to which it belongs and information about the developers who worked on the application. To modify the About page, do the following.

  1. Click Edit About Page for the appropriate application on the My Applications page.
  2. The Application Name field should be filled in automatically, but you can change it here if you want.
  3. In the Description of Application field, you can enter a more detailed description about your application that what appears in the Application Directory.
  4. You can choose up to two categories for your application. These categories serve to filter your application in the Application Directory so it can be found more easily when a user browses applications.
  5. For Developer Information, select whether your application was developed by a company or one or more individual developers.
    If a company developed the application, enter the company's name, website and description in the appropriate fields.
    If one or more individual developers created the application, provide information about them in the About the Developers field. To edit the list of developers, click Edit Developers. The application settings page appears.
  6. Click Submit to save your changes. You are prompted to upload an image for your application, which appears on the About page. The file can be a GIF, JPG or PNG no larger than 4MB in size.
  7. Browse for the image then click Upload Picture.
  8. To review the About page, click View About Page.

Editing Your Application Settings

You can change any configuration settings you've made for your application. Click Edit Settings. The Edit page for your application appears, where you can change any basic, optional, installation and integration settings, as discussed previously. Click Save to save your changes.

Viewing Statistics About Your Application

You can view statistics about your application. Go to the My Applications page and click Stats for an application. The Application Stats page appears. The statistics shown include:

  • The number of users who used the application in the past 24 hours.
  • The total number of users who have added your application.
  • The number of users who have added, removed, blocked and unblocked your application in the past 24 hours.
  • Any reviews users have written about your application.
  • A summary of sampled HTTP requests for your application and their return statuses.

Note: This page will continue to evolve with new metrics and tools.

Deleting an Application

You can delete your applications from this page as well. This removes the application from the Application Directory and from the profile of any user who added it, without any notification.

  1. Go to the My Applications page and click Delete App. The Delete API Key page appears.
  2. To confirm the delete, click Delete. Note that you cannot undo this action. If you accidentally delete an application, you can recreate it.

Submitting an Application

You can submit your applications to the Facebook Application Directory; from the My Applications page — just click Submit Application next to the appropriate application.

Troubleshooting Your Application

If you have questions or issues about developing a Facebook application, you can look for more answers on the Facebook website. You can start with the resources provided here. For basic information about developing a Facebook application, read more of the Facebook Developers Wiki. While Facebook maintains the wiki, we encourage developers such as yourself to contribute to the effort.

Finding a Web Host

If you are looking for a Web host for your application, check out the following forum threads:

Testing Your Applications

You can test your code with these tools.

When Facebook pushes new code each week, you can test your applications against it.

Getting Technical Support

If you don't find what you're looking for in the wiki and you need technical support from Facebook, use the following resources:

Filing Bugs

If you have found a bug in the Facebook Platform, go to our Facebook Platform Public Bug Tracking System at http://bugs.developers.facebook.com/ and, after searching for any existing reports, file a bug there to bring it to the attention of the Facebook Platform engineering team.

Retrieved from "http://wiki.developers.facebook.com/index.php/Creating_a_Platform_Application"
reference