Facebook “Open Graph Tutorial Step by Step”

Facebook almost launched Graph Search!
https://www.facebook.com/about/graphsearch
Time to share some tips and tricks on OpenGraph.
Step by step tutorial:

Step 1: Create a Facebook App

To create a Facebook app, go to the App Dashboard, click the ‘Create New App’ button. In the resulting popup box, enter your app name and an optional namespace (e.g., “mycompanyappname”) to get started. The namespace must be unique compared to all apps on Facebook.

Open Graph protocol

Once you have entered the initial information you will land on the Basic Settings page. Let’s examine some of the functionality on this page.

  1. Basic Info: This is where you can set your app’s name, namespace, and your contact email address.
    1. Display Name. This is the name that will appear in Login Dialog boxes as well as Open Graph actions.
    2. Namespace. Your app namespace. This should be unique to your app and will be used to manage your objects and actions.
    3. Contact Email. Enter your email address here.
    4. App Domains. This is the domain on which your app will be deployed. For example, “mycompany.com”.
    5. App Category. Select a category for your app that best represents what your app is and does. Note: If you haven’t selected a category for your app, we will classify it for you. If your app doesn’t fit logically into the category you’ve chosen, we may reclassify it in a more accurate category.
    6. Sandbox Mode. For the purposes of this tutorial, we will keep this Disabled.
  2. Select how your app integrates with Facebook:
    1. Select the ‘Website with Facebook Login’ choice (for the tutorial, we will demonstrate a website integration with Open Graph). A green checkbox should appear to the left and a Site URL field should appear.
    2. Enter a Site URL (your website location). The domain should match the App Domains entry in the Basic Infosection


Step 2: Authenticate Users

In order to publish Open Graph Actions, your app needs to prompt users for the publish_actions permission. You can use the Login Button plugin and set the ‘scope’ parameter to prompt for this permission.

Here is some code, using the JavaScript SDK, to help you get started right away.

Simply copy and paste the following code into a new HTML file and save (or publish) it to your chosen web server. Remember to replace [YOUR_APP_ID] with your own app information.

<html xmlns="http://www.w3.org/1999/xhtml" dir="ltr" lang="en-US" xmlns:fb="https://www.facebook.com/2008/fbml"> <head> <title>OG Tutorial App</title> </head> <body> <div id="fb-root"></div> <script> window.fbAsyncInit = function() { FB.init({ appId : '[YOUR_APP_ID]', // App ID status : true, // check login status cookie : true, // enable cookies to allow the server to access the session xfbml : true // parse XFBML }); }; // Load the SDK Asynchronously (function(d){ var js, id = 'facebook-jssdk'; if (d.getElementById(id)) {return;} js = d.createElement('script'); js.id = id; js.async = true; js.src = "//connect.facebook.net/en_US/all.js"; d.getElementsByTagName('head')[0].appendChild(js); }(document)); </script> <fb:login-button show-faces="true" width="200" max-rows="1" scope="publish_actions"> </fb:login-button> <h3>Stuffed Cookies</h3> <p> <img title="Stuffed Cookies" src="http://fbwerks.com:8000/zhen/cookie.jpg" width="550"/> </p> </body> </html>


Step 3: Define Objects, Actions and Aggregations

The Open Graph tab of the App Dashboard shows the “Getting Started” subtab of the tool:

Define Object Types and Action Types

The Getting Started wizard walks you through the process of defining your initial object type and action type.

  • Click the ‘Open Graph’ tab under your app settings.
  • Click the ‘Getting Started’ subtab.

In this tutorial, you will set up your app so that users will be able to Cook a Recipe. In order to do so, we will define an action (or verb) type called Cook and define an object (or noun) type called Recipe.

  • Enter cook in the verb field and recipe in the noun field.
  • Then, click the ‘Get Started’ button.

The next step in the wizard allows you to further define your custom action typeCook, with custom properties and sample data. We will use the default configuration in this tutorial, so click on the Save Changes and Next button.

 

Now, you are able to further define your custom object typeRecipe, with custom properties and sample data. We will again use the default configuration in this tutorial, so click on the Save Changes and Next button.

Define an Aggregation

Finally, after defining both an initial custom action type and custom object type, you are now able to define an aggregation.

 

When a user interacts with your app in a meaningful way, we will also highlight these actions on the user’s Timeline with an aggregation.

Let’s create an aggregation to highlight a list of recipes that were cooked:

  1. Data to Display - We’re looking for a list of cook actions, so enter Cook here.
  2. Layout Style - Select List
  3. Sort By - Select Most Recent
  4. Aggregation Title - Enter a user-friendly title for the aggregation, such as “Recently Cooked Recipes”
  5. Caption Lines - You can reference both properties of the object and action here. Let’s leave this blank for now for this tutorial, but feel free to read about more info on how to use captions.
  6. Timeline Preview - Preview of how your aggregation will appear in a user’s Timeline.

Click the Save and Finish button to save all your changes and return to the Open Graph dashboard. You are now done with defining your initial object types, action types and aggregations. The Dashboard view of your Open Graph app settings will show a summary of these configurations.

The next section will walk you through on how to get your app to publish its first Open Graph action and display an aggregation on a user’s Timeline.


Step 4: Publish Actions

Before being able to publish an Open Graph action for a user and having define its corresponding connected object type inStep 3, you will now need to create a publicly accessible web page that represents this object using Open Graph metatags. Once this object page is created, you can use the Graph API to publish an action.

Create an Object Page

The Open Graph Dashboard page has a ‘Get Code’ link next to Recipe object type. This contains the Open Graph meta tags describing the object that you’ll need to include on your web page.

  • Copy and paste this code snippet into a web page. Make sure to host your web page in a location where Facebook will be able to access it via HTTP GET.
  • Use the Debugger Tool to verify your meta tags are set up correctly by inputting your object web page URL. Resolve any warnings generated.
  • Note the object page URL because you will be using it to publish the related action

Here is an object page with the <meta> tags added. Remember to replace [YOUR_APP_NAMESPACE] and [YOUR_APP_ID] with your own app information.

<html xmlns="http://www.w3.org/1999/xhtml" dir="ltr" lang="en-US" xmlns:fb="https://www.facebook.com/2008/fbml"> <head prefix="og: http://ogp.me/ns# [YOUR_APP_NAMESPACE]: http://ogp.me/ns/apps/[YOUR_APP_NAMESPACE]#"> <title>OG Tutorial App</title> <meta property="fb:app_id" content="[YOUR_APP_ID]" /> <meta property="og:type" content="[YOUR_APP_NAMESPACE]:recipe" /> <meta property="og:title" content="Stuffed Cookies" /> <meta property="og:image" content="http://fbwerks.com:8000/zhen/cookie.jpg" /> <meta property="og:description" content="The Turducken of Cookies" /> <meta property="og:url" content="http://fbwerks.com:8000/zhen/cookie.html" /> </head> <body> <div id="fb-root"></div> <script> window.fbAsyncInit = function() { FB.init({ appId : '[YOUR_APP_ID]', // App ID status : true, // check login status cookie : true, // enable cookies to allow the server to access the session xfbml : true // parse XFBML }); }; // Load the SDK Asynchronously (function(d){ var js, id = 'facebook-jssdk'; if (d.getElementById(id)) {return;} js = d.createElement('script'); js.id = id; js.async = true; js.src = "//connect.facebook.net/en_US/all.js"; d.getElementsByTagName('head')[0].appendChild(js); }(document)); </script> <h3>Stuffed Cookies</h3> <p> <img title="Stuffed Cookies" src="http://fbwerks.com:8000/zhen/cookie.jpg" width="550"/> </p> </body> </html>

Publish an Action

Publishing an action connects the user to the object you created. The Open Graph Dashboard page has a ‘Get Code’ link next to your action. This contains curl code snippets that you can copy into terminal and run directly.

Publishing an action involves making an HTTP POST to the me/[app_namespace]:[action_type] Graph API endpoint with the following parameters:

  • [object_type]: a link to a web page representing an object.
  • access_token: a valid user access_token with publish_actions permissions.

For example, sending a POST to:

POST  https://graph.facebook.com/me/[YOUR_APP_NAMESPACE]:cook
         ?recipe=OBJECT_URL&access_token=ACCESS_TOKEN

This will publish a Cook action for the Recipe corresponding to the provided OBJECT_URL. Replace OBJECT_URL with your object web page URL.

Here is the updated sample app with the Cook action creation enabled when clicking the “Cook” button:

<html xmlns="http://www.w3.org/1999/xhtml" dir="ltr" lang="en-US" xmlns:fb="https://www.facebook.com/2008/fbml"> <head prefix="og: http://ogp.me/ns# [YOUR_APP_NAMESPACE]: http://ogp.me/ns/apps/[YOUR_APP_NAMESPACE]#"> <title>OG Tutorial App</title> <meta property="fb:app_id" content="[YOUR_APP_ID]" /> <meta property="og:type" content="[YOUR_APP_NAMESPACE]:recipe" /> <meta property="og:title" content="Stuffed Cookies" /> <meta property="og:image" content="http://fbwerks.com:8000/zhen/cookie.jpg" /> <meta property="og:description" content="The Turducken of Cookies" /> <meta property="og:url" content="http://fbwerks.com:8000/zhen/cookie.html"> <script type="text/javascript"> function postCook() { FB.api( '/me/[YOUR_APP_NAMESPACE]:cook', 'post', { recipe: 'http://fbwerks.com:8000/zhen/cookie.html' }, function(response) { if (!response || response.error) { alert('Error occured'); } else { alert('Cook was successful! Action ID: ' + response.id); } }); } </script> </head> <body> <div id="fb-root"></div> <script> window.fbAsyncInit = function() { FB.init({ appId : '[YOUR_APP_ID]', // App ID status : true, // check login status cookie : true, // enable cookies to allow the server to access the session xfbml : true // parse XFBML }); }; // Load the SDK Asynchronously (function(d){ var js, id = 'facebook-jssdk'; if (d.getElementById(id)) {return;} js = d.createElement('script'); js.id = id; js.async = true; js.src = "//connect.facebook.net/en_US/all.js"; d.getElementsByTagName('head')[0].appendChild(js); }(document)); </script> <h3>Stuffed Cookies</h3> <p> <img title="Stuffed Cookies" src="http://fbwerks.com:8000/zhen/cookie.jpg" width="550"/> </p> <br> <form> <input type="button" value="Cook" onclick="postCook()" /> </form> </body> </html>

Now click the “Cook” button! If the publish to Open Graph is successful, an id will be returned that represents the newly published action. Congratulations! You have now published an action and completed the basic steps in getting your Open Graph app up and running.

In order to view an aggregation on a user’s Timeline, your app will need to publish a few more actions to Open Graph on behalf of the user. Define a few more objects through the earlier steps and publish a few more actions. Your app will need to publish actions for at least 5 times before an aggregation is surfaced on a user’s Timeline.

Go to Timeline on Facebook to view the aggregation of your app:

Previewing Stories from Published Actions

You can preview News Feed stories created when publishing actions by going tohttps://www.facebook.com/USER_ID/activity/STORY_ID, where USER_ID is the user’s Facebook ID or username, andSTORY_ID is the action-instance-id as described below. The user must have appropriate permissions in order to see the preview.

Publishing Past Actions

Open Graph also provides the ability to publish a user’s past actions and objects. Please refer to our developer documentation on Publishing Past Actions.


Step 5: Add Social Plugins

Add one or more Social Plugins that are available for Open Graph apps.

On your object web page, you can add any of these plugins to highlight Open Graph actions. For the purposes of this tutorial, let’s add the new Activity Plugin.

Activity

The Activity Plugin has been updated to highlight the Open Graph actions published by an app.

To add an Activity Plugin, include the following code on your web page:

<fb:activity actions="[YOUR_APP_NAMESPACE]:ACTION-TYPE"/></fb:activity>

Here is the entire code of the tutorial that includes publishing an Open Graph action and rendering the Activity Plugin, all within a single page:

<html xmlns="http://www.w3.org/1999/xhtml" dir="ltr" lang="en-US" xmlns:fb="https://www.facebook.com/2008/fbml"> <head prefix="og: http://ogp.me/ns# [YOUR_APP_NAMESPACE]: http://ogp.me/ns/apps/[YOUR_APP_NAMESPACE]#"> <title>OG Tutorial App</title> <meta property="fb:app_id" content="[YOUR_APP_ID]" /> <meta property="og:type" content="[YOUR_APP_NAMESPACE]:recipe" /> <meta property="og:title" content="Stuffed Cookies" /> <meta property="og:image" content="http://fbwerks.com:8000/zhen/cookie.jpg" /> <meta property="og:description" content="The Turducken of Cookies" /> <meta property="og:url" content="http://fbwerks.com:8000/zhen/cookie.html"> <script type="text/javascript"> function postCook() { FB.api( '/me/[YOUR_APP_NAMESPACE]:cook', 'post', { recipe: 'http://fbwerks.com:8000/zhen/cookie.html' }, function(response) { if (!response || response.error) { alert('Error occured'); } else { alert('Cook was successful! Action ID: ' + response.id); } }); } </script> </head> <body> <div id="fb-root"></div> <script> window.fbAsyncInit = function() { FB.init({ appId : '[YOUR_APP_ID]', // App ID status : true, // check login status cookie : true, // enable cookies to allow the server to access the session xfbml : true // parse XFBML }); }; // Load the SDK Asynchronously (function(d){ var js, id = 'facebook-jssdk'; if (d.getElementById(id)) {return;} js = d.createElement('script'); js.id = id; js.async = true; js.src = "//connect.facebook.net/en_US/all.js"; d.getElementsByTagName('head')[0].appendChild(js); }(document)); </script> <h3>Stuffed Cookies</h3> <p> <img title="Stuffed Cookies" src="http://fbwerks.com:8000/zhen/cookie.jpg" width="550"/> </p> <br> <form> <input type="button" value="Cook" onclick="postCook()" /> </form> <fb:activity actions="[YOUR_APP_NAMESPACE]:cook"></fb:activity> </body> </html>


Step 6: Submit Your Actions For Approval

We are introducing a lightweight review and approval process before your app can publish Open Graph actions to all users.

 

 

Open Graph activities will be immediately visible to the administrators, developers and testers of your app. This allows you to do end-to-end testing of your Open Graph integration. Once that is complete, submit the Open Graph actions of your app via the App Dashboard for review and approval.

After we have verified that the use of Open Graph actions by your app meets our criteria, we will approve your app to publish Open Graph actions to all Facebook users. Please note that we are not approving your app, only how Open Graph actions are being published by your app.

Read more about the approval process for further details.


Debug and Troubleshoot

Here are some helpful tips when troubleshooting issues in publishing Open Graph objects or actions by your app:

How to verify your Objects are in the Open Graph

  • Use the Object Debugger to validate your objects to make sure you have included the needed meta tags.

How to verify your Actions are published to the Open Graph

  • Make sure your objects are properly defined with the Object Debugger
  • Make sure you are using the right namespace for your API calls. Remember that an application namespace cannot be modified once set.
  • Make sure you have removed the &expires token from your access_token before making the Graph API call
  • Make sure you are getting an id returned from the Graph API POST call

Why am I getting “This method must be called with an app access_token” error when publishing an action?

  • Uncheck the “Require app access token to write” checkbox on the configuration page (hidden under the Advanced section) for your Open Graph action type in the App Dashboard.

Next Steps

Share/Bookmark