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.
- Basic Facebook app creation knowledge
- Basic Git knowledge
- A Heroku user account. Signup is free and instant.
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: email@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.
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.
As a quick start, clone this demo Ruby application:
$ git clone https://github.com/jonmountjoy/facebook-template-ruby $ cd facebook-template-ruby
Now create the Heroku application:
$ heroku create $ Creating radiant-tor-1481 in organization heroku... done, region is us http://radiant-tor-1481.herokuapp.com/ | firstname.lastname@example.org:radiant-tor-1481.git
Note the URL of the application.
Now deploy the app source code to Heroku:
$ git push heroku master
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:
$ heroku config:set FACEBOOK_APP_ID=133333333463066 \ FACEBOOK_SECRET=a7244e333333333a7a2bf9492a6089a0
Note how the application uses these config vars when authenticating against the Facebook API:
def authenticator @authenticator ||= Koala::Facebook::OAuth.new(ENV["FACEBOOK_APP_ID"], ENV["FACEBOOK_SECRET"], url("/auth/facebook/callback")) end
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
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
<p>Welcome to your Facebook app, running on <span>heroku</span>!</p>
Use your favorite text editor to change this line to:
<p>This is my app, I can edit it all I want.</p>
Save the file, then use your terminal to commit the change to Git:
$ git commit -am "changed greeting" [master 0ff313a] changed greeting 1 files changed, 1 insertions(+), 1 deletions(-)
2) Deploy to Heroku
Now, the fun part – pushing the modified code up to Heroku with
git push heroku master:
$ git push heroku Counting objects: 5, done. Delta compression using up to 4 threads. Compressing objects: 100% (3/3), done. Writing objects: 100% (3/3), 291 bytes | 0 bytes/s, done. Total 3 (delta 2), reused 0 (delta 0) -----> Ruby/Rack app detected -----> Using Ruby version: ruby-1.9.3 -----> Installing dependencies using Bundler version ... Using json (1.5.5) Using multi_json (1.0.3) Using koala (1.3.0) Using tilt (1.3.3) Using sinatra (1.2.6) Your bundle is complete! It was installed into ./vendor/bundle Cleaning up the bundler cache. -----> Discovering process types Procfile declares types -> web Default types for Ruby/Rack -> console, rake -----> Compiled slug size: 14.5MB -----> Launching... done, v7 http://radiant-tor-1481.herokuapp.com deployed to Heroku To email@example.com:radiant-tor-1481.git 396ec84..994290d master -> master
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.
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
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
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.