Custom Stories on the Web

This document describes the key steps to publish your first story with Open Graph.

Before getting started, you'll need to:

Once you're done with this guide, you can also learn about possible next steps.

Create a Facebook App ID

You may already have a Facebook App ID for your project. You can use the same App ID across multiple platforms e.g. iOS, Android and a Website.

If you don't already have a Facebook App ID for your project, you first should create one:

Create a new App ID

This will create a popup box will prompt you to enter two things:

  • A display name. This is the app name used when stories are published to Facebook and in a number of other places. Use Open Graph Getting Started or something similar.
  • A namespace. Not required for this guide so just leave it blank.
  • A category. This will determine the kind of app that you're building. For now, just select Communication.

Once you've created your app you'll be provided with a dashboard that shows User and API Stats. From this screen, click on Settings on the left.

Complete the following fields, as shown in the screenshot below:

  • Contact Email. Your developer email address.
  • App Domains. The domain that your app will be hosted on (without the http:// or https:// prefix.)

This example is a basic web page, so you will need to add the web as a platform. Click Add Platform at the bottom of the page and select Website.

Enter a path where you will want to store your file, which will be given to you below.

When you're done, click Save Changes at the bottom.

Set Up the App

Place the following file at the URI you specified in the settings above.

In the file, you need to change one item, which is the App ID. Search for 'fbAppId' in the file and replace its value with the App ID listed at the top of the Settings page in the App Dashboard.

<title>Open Graph Getting Started App - og.likes</title>
<style type="text/css">
div { padding: 10px; }
<meta charset="UTF-8">
<script type="text/javascript">
  // You probably don't want to use globals, but this is just example code
  var fbAppId = 'replace me';
  var objectToLike = '';

  // This check is just here to make sure you set your app ID. You don't
  // need to use it in production. 
  if (fbAppId === 'replace me') {
    alert('Please set the fbAppId in the sample.');

   * This is boilerplate code that is used to initialize
   * the Facebook JS SDK.  You would normally set your
   * App ID in this code.

  // Additional JS functions here
  window.fbAsyncInit = function() {
      appId      : fbAppId, // App ID
      status     : true,    // check login status
      cookie     : true,    // enable cookies to allow the
                            // server to access the session
      xfbml      : true,     // parse page for xfbml or html5
                            // social plugins like login button below
      version		 : 'v2.7',  // Specify an API version

    // Put additional init code here

  // Load the SDK Asynchronously
  (function(d, s, id){
     var js, fjs = d.getElementsByTagName(s)[0];
     if (d.getElementById(id)) {return;}
     js = d.createElement(s); = id;
     js.src = "//";
     fjs.parentNode.insertBefore(js, fjs);
   }(document, 'script', 'facebook-jssdk'));

   * This function makes a call to the og.likes API.  The
   * object argument is the object you like.  Other types
   * of APIs may take other arguments. (i.e. the book.reads
   * API takes a book= argument.)
   * Because it's a sample, it also sets the privacy
   * parameter so that it will create a story that only you
   * can see.  Remove the privacy parameter and the story
   * will be visible to whatever the default privacy was when
   * you added the app.
   * Also note that you can view any story with the id, as
   * demonstrated with the code below.
   * APIs used in postLike():
   * Call the Graph API from JS:
   * The Open Graph og.likes API:
   * Privacy argument:

  function postLike() {
       { object: objectToLike,
         privacy: {'value': 'SELF'} },
       function(response) {
         if (!response) {
           alert('Error occurred.');
         } else if (response.error) {
           document.getElementById('result').innerHTML =
             'Error: ' + response.error.message;
         } else {
           document.getElementById('result').innerHTML =
             '<a href=\"' +
    + '\">' +
             'Story created.  ID is ' +
    + '</a>';

  Login Button

  This example needs the 'publish_actions' permission in
  order to publish an action.  The scope parameter below
  is what prompts the user for that permission.


This example creates a story on Facebook using the
<a href="">
<code>og.likes</code></a> API.  That story will just say
that you like an
<a href="">
article on TechCrunch</a>.  The story should only
be visible to you.

  value="Create a story with an og.likes action"

<div id="result"></div>


Publish a Story

If you load the app, you should see the following:

Log in, authorize the app to post to your timeline and click the "Create a story..." button. You should see something like this:

You'll note that the result is listed below the button. If you click it, it takes you to the activity that was created on Facebook. It should look something like this:

You should notice a few things about the activity on Facebook:


The light-blue dashed border around the outside indicates that the post is only visible to you. A post visible to friends or public won't have a border, although it will have an icon to replace the lock to indicate how widely it's shared. You can set the privacy of a post with the privacy parameter, included with the demo code. Developers don't usually include a privacy parameter, instead allowing the default privacy of the app to dictate how widely something is shared.

Actions and Objects

The center part of the story is very important. It says that "[subject] likes an article on [app]". The 'likes' was driven by the API that you used. og.likes creates like stories. If you had used the book.reads API instead the story probably would have said something like " reading..." or " ." The like API, which we call an Action, is roughly the same as a verb.

The "article" part of the story is also very important. The page in question has tags that describe what it is and how it should be displayed on Facebook. If you look at the source for the page you'll see that it contains a tag that tells Facebook what kind of content it is:

<meta property="og:type" content="article" />

This is how Facebook knows that it's an article as opposed to, say, a book.

<meta property="og:type" content="book" />

These tags are what we use to describe Objects. Objects are roughly equivalent to nouns. Objects are closely tied to the Actions you use. For example, books.reads can take a book argument. fitness.runs requires a course object. og.likes is special in that it can accept any object.

Submit Your Actions For Review

If your app will be creating stories, then your actions require review. Click on App Review on the left hand side of the App Dashboard and you should see something like this:

Click on Start a Submission and you will see a screen like this:

In Step 3, we talked about how stories were made up of actions and objects. In this case, your story used the like action, and that's what needs approval. (The App Center approval is there if you want to submit your app to Facebook's app center. The App Center is where people find interesting apps, and is something you should consider to drive distribution of your app when you're ready.)

In order to complete the submission process, you need to provide an app logo (a 75x75px image) and an app icon (16x16px image), instructions on how to test it with screenshots and an automatically created test user. The submission process shouldn't block your ability to test your own changes, since you and anyone else you add as a developer can always post and test your own stories.

If you want to learn more about the submission process, see our Understanding the Open Graph Submission Process document. It gives overall guidance on what Facebook looks for when approving the stories that apps can create. As a smaller example, provide specific guidance about how to use the like action in your app. We generally complete reviews within three working days.

Actions don't show up in the list for approval until you've used them once from your app. So when you're ready to add your own you're going to need to create at least one action from your app before you can submit it for approval.

Next Steps

Here are the next steps you can take in learning Open Graph: