Starting your first facebook application is frustrating from the get-go. After taking a few lumps I have decided to break the new application form down field by field to try and make it simple for you. The fields are done in the order that they appear.

Application Name:

This is the name you want to give your application; I obviously chose to name mine “AjaxNinja Labs.” Your application name will appear everywhere, for instance, if you add a sidebar URL for your app, the name will appear under your list of applications like this:

Facebook side navigation bar with my application (AjaxNinja Labs) at the bottom

In short, your application name is ubiquitous; it will appear EVERYWHERE your application can be found. Pretty straight forward.

Support Email:

This is your support email address for your application… Should absolutely be an address where you or one of the other developers can be contacted. This is a required field, but for the sake of avoiding spam, I have blurred out my email address.

Callback URL:

This is where things start to get confusing; a callback URL is meant to be the root directory, WITH THE SLASH INCLUDED, of the content for your facebook application on your server. For my application, the root directory is that of my labs area; this callback URL is crucially important as it is your end of the Facebook application service. If this URL is not provided correctly your application will not work.

Facebook call back URLs work essential like proxy servers, including caching. The reason for this? Obviously Facebook doesn’t want applications with crappy hosts diminishing the results for its users, so it caches FBML (Facebook Markup Language) output and checks periodically for updates. Here is a diagram of how Facebook proxying and call backs work:

Note: I do not know how the Facebook caching algorithms work or how often they request updates from your source.

Canvas Page URL:

As you may have seen in the diagram above, the canvas page URL is simply the Facebook virtual directory pointing for the content in your application. This value can be totally arbitrary as long as the URL is available and 7 characters or longer.

FBML or IFRAME:

I strongly recommend using the iframe option, simply because it allows you to design a website under the hood that behaves and acts like a normal website. However, using a FBML markup file instead of a native .ASPX, .PHP, or .HTML file will allow you to use a lot more native tools for facebook and it will render faster. If you’re concerned about taking on major performance hits, FBML is the way to go. If you’re more interested in keeping things simple, stick to an iframe.

Application Type:

This one is pretty simple; if you’re designing a desktop application that connects to Facebook for some operations, then check the desktop option. If you’re designing an application that can be run off of your website, then pick website.

IP Addresses:

If you have some security concerns regarding your application and you want to whitelist all of the allowed IP addresses making service requests, you can enter those IP addresses here. Most applications do not use this feature, generally speaking.

Can your application be added on Facebook:

If you want users to be able to add your application to their facebook account, then check the yes button. This means that users will be able to access the canvas page, add your application to their profiles, and post news feed items regarding your application.

POTENTIAL PIT FALL: If you are still in the development stage of your application, don’t check the “no” button because you want to prevent users from accessing your application, as this will also prevent you and any developers you are working with from testing the application as a user; check the “only developer’s may install application” checkbox further down the page to prevent normal users from tampering with your application in production.

Terms of Service (TOS) URL:

The terms of service URL is meant to be a link to a terms of service document hosted on your server; unless you’re trying to build a Facebook app where you can potentially run into some privacy issues, I’d recommend leaving this blank.

Application Icon:

First, every application should have an icon, period. Your icon will be shown alongside your application name in every instance the app name is displayed, so it’s important for establishing branding. The icon dimensions are 16 by 16 pixels and it must in the GIF format.

Post-Add URL:

This URL can be on your local hosting, and users are redirected from Facebook to here immediately after adding your application. I just goofed around a put a random link to one of my blog entries on there, but if you want to do something like send them to an instructions page, this is the place to do it.

Application Description:

Self-explanatory. This is the description that appears next to your application on the “About Application XYZ….” page.

Post-Remove URL:

Update from AjaxNinja Reader Harry:

When a user selects to remove your application they are not sent to the ‘Post-Remove URL’ as they have removed the application and so will have no further contact with it. A POST request will be sent to this address in the background however containing the uid of the leaving user.

Thanks, Harry for helping us clear up what the Post-Remove URL does!

Default FBML:

This is the FBML that will be visible in the profile by default. Example:

Default Profile Box Column:

There are two columns on any Facebook profile page: the wide one on the right and the narrow one on the left. Users can drag and drop your application on their profile to either column, but if you want to specify a default column you can do it here. Here’s what they look like:

Narrow Column:

Wide Column:

Developer’s Only Mode:

If you don’t want any noobs (normal people) messing around with your application while you’re still in the process of developing and testing it, check this button.

Side Nav URL:

This is an important one. If you want Facebook users who have installed your application to be able to access it via sidebar, you need to provide them with a URL so they can have a link on their sidebar. For many applications this link is the application’s primary entry point.

Nota Bene: Notice how I have used an internal Facebook link here… this is how I get Facebook to actually implement my iframe within a Facebook page.

Privacy URL:

If you have some custom privacy options that you’d like your users to be able to set, place a URL to that here. Again, it can be internal like my sidenav example or external.

Help URL:

If you have a help page for your users you can place a link to it (internal or external to Facebook, again) here. Although I have no idea where it actually appears as I have tried looking for mine.

Private Installation:

If you want to prevent information about your application from appearing on news feeds or mini feeds then check this box.

Upload URLs:

If you want to allow uploads in your application you need to fill out both of these fields. Frankly, I don’t know quite how the action field works, but the callback URL is just your local URL for handling the file upload.

Leave some suggestions, comments, or improvements!

Also, be sure to check out this sweet first facebook app tutorial on Tucows.

If you enjoyed this post, make sure you subscribe to my RSS feed!