FaceBook Real-Time Updates API Tutorial - Part I

"The Graph API supports real-time updates to enable your application using Facebook to subscribe to changes in data in Facebook. Your application can then cache data and receive updates, rather than polling Facebook’s servers. Caching data and using this API can improve the reliability of your application and decrease its load times.

Whenever a subscribed change occurs, Facebook makes an HTTP POST request to a callback URL you specify with a list of changes. Your application will generally receive notification of the change within a couple of minutes of its occurrence."

Tutorial
Understanding the documentation for this API can be quite frustrating for some, and it seems like many people are really struggling with understanding how to get updates and how how to handle them. I therefor decided to write a full length tutorial explaining each step in great detail. This part I of a three-part tutorial series on the FaceBook Real-Time Updates API will cover how to subscribe to real-time updates.

The documentation for this API can be found at the bottom of this post.

Here are the steps to set up a subscription:

1) Set up an endpoint URL that receives both HTTP GET (for subscription verification) and POST (for actual change data) requests from Facebook.

Setting up the endpoint URL:

This first step is actually quite easy if you didn't miss the tiny link to the sample code at the bottom of the documentation page.

- Create a php file and copy-paste the code below into the file
- Change the defined VERIFY_TOKEN to be something else than yourownsecretstring
- Upload the file to your server


Code:


Okay, thats it for the first step! Now we are ready to move onto the next step!

2) Make a POST to the graph API url https://graph.facebook.com/yourappid/subscriptions to subscribe, and be ready to handle the verification request.

Making a POST to the graph API
Before we can create a subscription we will need an access token.

Access token
This token is easily obtained by opening your web browser and copy-pasting the following into the address field:

https://graph.facebook.com/oauth/access_token?grant_type=client_credentials&client_id=APP_ID&client_secret=APP_SECRET

It should look something like this: 1234567891234|ABcDeFG1H2I34jklmNopQrstUvw5xYZ

(For those of you who don't remember where to find your app id and app secret, just go to https://developers.facebook.com -> Apps -> YourApp)

Creating the subscription

Now that we have our access token we can finally go ahead and create a subscription.

This is done by again simply opening your web browser and copying in the code below. Before you do this however, make sure that you can reach the php-file that you have set up. For this tutorial we will just subscribe to feed, but if you need to subscribe to multiple connections then all you have to do is separate them with a comma. (i.e. fields=feed, friends, events)

https://graph.facebook.com/yourappid/subscriptions?access_token=youraccesstoken&object=user&fields=feed&verify_token=yourownsecretstringsetinyourphpfile&method=post&callback_url=http://www.yourwebsite.com/facebook_subscribe.php

When the page is loaded, it should say null if the subscription was successful)

To check if your subscription is set up correctly
https://graph.facebook.com/yourappid/subscriptions?access_token=youraccesstoken&method=get

When the page is loaded, it should look like this:

{
   "data": [
      {
         "object": "user",
         "callback_url": "http://www.yourwebsite.com/facebook_subscribe.php",
         "fields": [
            "feed"
         ],
         "active": true
      }
   ]
}

To delete your subscription

https://graph.facebook.com/yourappid/subscriptions?access_token=youraccesstoken&method=delete


Conclusion
Aight, thats it for this tutorial! I hope that this has helped you to understand how to receive real-time updates from FaceBook.  

Please feel free to leave a short comment to let me know that this tutorial was of any use.

The second part of this tutorial-series will explain how to handle the notifications you receive from Facebook.

UPDATE:
FaceBook has now made it easier to add, modify, and delete subscriptions using their new Realtime Updates panel.

https://developers.facebook.com/docs/howtos/managing-realtime-update-subscriptions/

Documentation

The documentation for the FaceBook Real-Time Updates API can be found at: https://developers.facebook.com/docs/reference/api/realtime/