Facebook App and Timeline Integration (Actions, Objects and Aggregations)

In this tutorial we will see how to integrate your facebook app with user’s timeline. Facebook has recently introduced this feature, i.e apps have permission to publish information on user timeline.

This is a very powerful feature which facebook has provided and is very useful to virally spread your application.

This is an advanced facebook tutorial, so you should be familiar with based facebook integration first.
To given an idea of what you can do with timeline integration read below

  • Any action performed by user on your can be published to his timeline e.g if a user reads a blog, using app it can be published in the user timeline that he read a blog post.
  • You can create custom action’s and object’s depending on your website e.g User voted for a College, User read a Article, User participated in a Quiz. Here text written in italics are actions and objects respectively, and we can custom action,object as many as we want.

Attached is a screenshot of the it look on timeline, this was published on timeline by an app created by me on www.collegekhabar.com/ranking

Timeline App Integration

Timeline App Integration

Basic of timeline integration – Action, Object, Aggregation

There are few terms which are used when doing timeline integration. I will just explain them in brief here, using the sentences below
User voted for a College
User read a Article
User participated in a Quiz
Action:: Action is basically an adjective like in above cases vote, read, participated are actions. Read more here
Object: The entity on which actions are performed are called objects, like in above sentences College, Article, Quiz are objects. Read more here
Aggregation: This basically is used to define the display of how it will look in a user timeline when a user performs multiple actions on a object. Read more here

Developing timeline application

Now lets see in detail what are all the steps to follow to develop a timeline application.

First step is to create a basic facebook app and set it up on your domain.

Next you need to add this app to your website so that user can authenticate your app to publish actions to their timeline. To do this you need to put the facebook login button, as discussed in the previous tutorial.
But this time in our app permission we will add ‘publish_actions’ permission to our app scope. So basically our app scope would look like


Only after user has given permission to our app with ‘publish_actions’ scope can we publish actions to his profile.

Next we we need to define our custom actions and object to use in our application. To do this open your app in facebook developer website, and click on Edit Open Graph.

Facebook App Edit Open Graph

Facebook App Edit Open Graph

After you click on edit open graph, you will get a message from facebook to setup the app namespace.

Facebook Set App Namespace

Facebook Set App Namespace

Just go to the app summary page and set a unique app namespace. Remember this app namespace, as it will be required in all future api calls. I my case i have set my app namespace as ‘etechblog’.

Now again go back to the ‘Edit Open Graph’ page, here you need to setup your action and object. Now you will see a page where facebook asks you enter the action and object in a sentence. In my case, i have take action = ‘download’ and object = ‘module’.

Facebook Create Action

Facebook Create Action

After doing this click on ‘Get Started’ green button and facebook will create your action and object. In the next page you will see, facebook asks for more details about the action created. You can see details about this page here
Every thing is pre-filled in by default, so you can simple click on ‘Save Changes and Next’. The next page asks for details about the object created, read more here for details. After click on ‘Save Changes and Next’, the last page which shows up asks for details of the aggregation. You can read more about it here. Finally after finishing these steps you see a page like this

Facebook Action, Object and Aggregation

Facebook Action, Object and Aggregation

Next lets see how to publish user actions to his timeline from our website.
Its important to note here that the custom action you created cannot be directly published to users timeline. What i mean is that before being able to publish user actions, you need to approve your actions from facebook. But to initially to test your actions, the action will get published on your personal facebook account only from where you have created the app.

To submit your action to facebook for approval you need to click on the ‘Submit’ link in front of the action and follow their submission process. It took me about 2weeks time to get by action approved so please bear this in mind during development.

Facebook Submit Action

Facebook Submit Action

Now to publish an action, it can be done through php, javascript, facebook php-sdk and many other ways. But its important to remember that you should have a authenticated user access token to publish the actions, this basically means user should have approved your app for timeline access.

Code to publish through facebook php-sdk

$params = array('module'=>'www.websiteurl.com/page.php?id=3');
$out = $facebook->api('/me/etechblog:download','post',$params);
}catch(Exception $e){
echo $e->getMessage();

Code to publish through facebook javascript-sdk

FB.api('/me/etechblog:download', 'post', 
  { module : 'www.websiteurl.com/page.php?id=3' });

You can see more details of the above code here

Next important part, the url which we passed www.websiteurl.com/page.php?id=3. We need to setup meta tags in this page to set all properties of the object. In the file page.php you need add code like this

<head prefix="og: http://ogp.me/ns# fb: http://ogp.me/ns/fb# collegekhabar_etech: http://ogp.me/ns/fb/collegekhabar_etech#">
  <?php if(isset($_REQUEST['id'])) { 
  $info = $my_obj->getCompleteDetails($_REQUEST['collage']); ?>
  <meta property="fb:app_id"      content="XXXX" />  <!-- APP ID -->
  <meta property="og:type"        content="etechblog:module" />  <!-- app namespace:object --> 
  <meta property="og:url"         content="www.websiteurl.com/page.php?id=<?php echo $_REQUEST['id'] ?>" /> <!-- same as the url passed while publishing the action -->
  <meta property="og:title"       content="<?php echo $info[0]['collage_short']?>" /> <!-- get title from database -->
  <meta property="og:description" content="<?php echo $info[0]['collage_name']?>" /> <!-- get description from database -->
  <meta property="og:image"       content="http://www.collegekhabar.com/ranking/ranking/<?php echo $info[0]['logo']?>" /> 
<!-- get image from database -->
  <?php } else { ?>  <!-- Else condition required to prevent any errors -->
  <meta property="fb:app_id"      content="XXXXX" /> 
  <meta property="og:type"        content="etechblog:module" /> 
  <meta property="og:url"         content="www.websiteurl.com" /> 
  <meta property="og:title"       content="title" /> 
  <meta property="og:description" content="description" /> 
  <meta property="og:image"       content="images/logo.png" /> 
  <?php } ?>

The meta properties that you need to define comes from the object properties which you define when creating an object. Attached here is the screenshot from where you can add properties, also get the meta property name and value.

Facebook Timeline Object Properties

Facebook Timeline Object Properties

Here there is a very important thing to notice, the url given in <meta property=”og:url” /> is from where facebook will read the meta tags and not from the url given when publishing an action. You can also check the meta tags facebook is reading from your URL from http://developers.facebook.com/tools/debug. Just put your page URL in the debugger and press debug, it will show the tags facebook is able to read.

Facebook Debugger

Facebook Debugger

Facebook debugger is generally a useful tool, it can also be used to refersh the facebook cache for a particular url.

I think i have covered everything in this tutorial, from creating action,objects to publishing them.
  • jhouedanou

    Hello. How do you manage to show a ‘vote’, or a ‘want’ button in a magento product detail view ?

     I’ve set up a store on magento, and i’ve successfully made an facebook action, an object and an integration, and i’ve changed the head prefix and added the open graph metas in  .phtml files .
    The action has been approved by facebook, but i can’t get the button to work correctly .

    • Manish Prakash

      I need to view your source code only then I can determine? Do you get any error when you publish the action on facebook?

  • Hi Manish, I really find your Blog helpful. It is really good.

  • Pingback: Facebook Timeline App - Built in actions, objects, scores, achievements()

  • i want it to integrate in my WordPress blog can you please guide me steps


  • Afrer i publish activity i view details on popup (from database), but when i click that link it shows blank page… Kindly give me the solution

  • Magento Themes

    i will be having my hands on it…

  • is there possible if we user multiple actions per object?

    • Adrián Zulueta Feippe


  • How can we handle multiple action per object?

    Ex: I have two actions i.e. nominate & vote and one object i.e. nominee. And in aggregation, I have created two aggregation one is “People I have nominated” and other is “People I have voted”. But when I publish an action, it’s show only one aggregation at a time. Do you have any idea how to show both aggregation together?