Table of Contents

Facebook offers a rich set of APIs and several SDKs, making it easy to develop applications that interact with Facebook data and services. Such applications can be developed and deployed to Heroku, in any of Heroku’s supported languages.

This guide is for Facebook developers who develop and deploy their applications on Heroku.

It assumes no previous knowledge of Heroku, and will walk through every part of the process: creating an app and a Heroku account, setting up local development tools, and deploying changes to your Facebook app.

Local workstation setup

Once installed, you use the heroku command from your command shell. Log in using the email address and password you used when creating your Heroku account:

$ heroku login
Enter your Heroku credentials.
Email: adam@example.com
Password:
Could not find an existing public key.
Would you like to generate one? [Yn]
Generating new SSH public key.
Uploading ssh public key /Users/adam/.ssh/id_rsa.pub

Press enter at the prompt to upload your existing ssh key or create a new one, used for pushing code later on.

Workflow

There are four components to creating a Facebook application:

Creating the Facebook app on Facebook’s App Dashboard

Writing the source code for your app and deploying it to Heroku

Configuring the Heroku app to hold the Facebook App ID and Secret

Modifying the settings for your Facebook app to reference the Heroku app

Creating the Facebook app

Visit Facebook’s App Dashboard to create a new application. Click on “Create New App”.

After providing the app with a name and filling in the captcha, you’ll be placed into the settings area for the application. You’ll also be provided with an App ID and App Secret that will be needed later.

Creating the Heroku app

While we can’t write your app for you, this guide uses a simple demo Ruby app to illustrate the process. You can of course develop your Facebook app in any other language supported on Heroku, such as Java, Python or Node.js. Refer to the Facebook SDK documentation to find a suitable library for your language of choice - the general method of developing and deploying on Heroku is the same for each language.

Configure the Heroku app

This demo app, like most Heroku apps, uses config vars to store external, configuration information about the app. These config vars will be made available to the app at run time as ordinary environment variables. This app template uses two - the Facebook App ID and App Secret - which any Facebook app requires.

Set the config vars. Reference your Facebook application for the App ID and App Secret:

Configure the Facebook app

When you created the Facebook application, you were assigned a Heroku app name and a resulting URL - in this case it was http://radiant-tor-1481.herokuapp.com.

Take your Heroku app’s URL (run heroku info if you’ve lost it) and configure your Facebook application to use it.

Click on “Settings”

Click “Add Platform”

Select “Website”

Insert the Heroku app’s URL in the “Site URL” field, and save the changes.

At this point you should have a working application. Navigate to your Heroku app, or execute this from the command line:

$ heroku open

Congratulations! You now have your very own Facebook app, running on Heroku:

The demo app shows examples of accessing the Facebook API to list friends, photos, interests, and more. Once you start editing the code, you can use these capabilities to make your app do more interesting things.

Now that you’ve got a running app, you’ll want to start editing it.

Editing your app

With your Heroku account and local tools set up, you can start making changes to your Facebook app.

1) Make a change

Let’s tweak something small in the app and push it back up to Heroku, illustrating the deploy process. For example, find the line of HTML which shows the welcome banner in index.erb, in the views folder:

Reload the app in your browser. You should see the modified welcome banner:

Congratulations, you’re now a Facebook app developer!

You can now go to work on your application. When you’re ready to get more advanced in your editing techniques, move on to the next section.

Working locally

In the previous section, we pushed changes to the app to the live production environment without testing it in a local environment. A better workflow is running the app locally, and testing your changes there. When you’re ready to deploy, use git commit and git push heroku to push up changes to the live production app.

Methods for running your app on your local computer will vary by programming language and operating system, but typically you would use Foreman, installed as part of the Heroku Toolbelt, to start the application.

There are two techniques you’ll need to know about that are specific to running a local development version of a Facebook app.

1) Creating a development Facebook app

The Facebook settings for the app you previously created points at the URL of your Heroku app (which will look like https://furious-robot-218.herokuapp.com). This is the production app.

For development, you’ll need to register another app with Facebook. Unlike the first app, this one will not run on Heroku, but instead will run on your local workstation and have a URL like http://localhost:5000/.

To set up this second app, go to Facebook App Dashboard and again click Create New App. Choose a name to indicate that this is the development version of your existing app. For example, if your other app is named “My Cool App”, you might call this one “My Cool App - Dev”.

Once created, click the Website checkbox and enter your local URL. For example:

The click Save Changes.

2) Setting Facebook app environment variables

On the same settings page for your app used to set the website URL, you’ll also find the App ID and App Secret:

For your production app, you added these to your Heroku app as config vars, but in your local environment you’ll need to set them as environment variables.

Foreman automates this local environment configuration—it will automatically source a file named .env in the root of your app’s code checkout when it runs your app. Cut-and-paste your App ID and App Secret into .env:

FACEBOOK_APP_ID=964173273189
FACEBOOK_SECRET=dcd5d23d003d53cb2b68e01

Ready to test locally

With these two changes in place, you should be able to visit your app locally and access all Facebook functionality. When you’re ready to share your changes in the world, git commit them and then git push heroku, then visit your production app to confirm that your changes work correctly on the live app.