Open Graph Overview

In this document:

Telling Stories with Open Graph

Open Graph lets apps tell stories on Facebook through a structured, strongly typed API.
People use stories to share the things they're doing, the people they're doing them with and the places where they happen. Open Graph lets you integrate apps deeply into the Facebook experience, which increases engagement, distribution and growth.
Here's an example story from Goodreads:
People can view the same stories across multiple devices. Here's the same story viewed on iOS:
Publishing stories drives engagement and interest in your app. People can comment on their friends' stories and start a conversation:

How Open Graph Works

Integrating with Open Graph starts with your app. Facebook provides SDKs for iOS, Android, JavaScriptand PHP. Apps need to use Facebook Login, which allows users to sign into your app using their Facebook credentials. Once there's a relationship between your app, Facebook and the person, you can ask the person to publish stories from your app.
Four elements go into telling stories. Let's use 'Christopher finished reading The Name of the Wind on Goodreads' as an example:
The actor: This is the person who published the story, in our case 'Christopher'.
The app: This is the app that publishes the story on the actor's behalf. Every story is generated by an app and every story includes the app used to create it.
The action: This is the activity the actor performs, in our case 'finished reading'. Facebook provides a number of common actions that can be used to create stories, like watch or read or you can create your own stories and actions.
The object: This is the object the actor interacts with, 'The Name of the Wind', a book. Objects may be created two different ways. These include:
  • Adding metadata to a publicly accessible web page hosted on the Internet. Almost any web page can be an object. In this form, objects are public information.
  • You can use Facebook's Object API to create objects that are hosted on Facebook's servers. These objects can be private to individual users or global in the context of an app.
Please see our guide on Using Objects to learn more about both methods of creating objects.
If there is no common action available that meets your needs, you can create your own custom action type. For example, if you're building an app to track rock climbing you may want to make an action 'climb' where the object is a mountain. The story can include a picture and the geographic location of the mountain. By adding additional data you can create a compelling story to share with friends and make your app a part of how people express themselves to others.

Review Process

It's very important that all stories told on Facebook are high quality and don't surprise the person using your app. This means that all apps that want to use Open Graph must go through a review process for the stories they create. You can learn more about this process in our submission process document. Reviews are pretty quick, generally done within three business days.

Privacy

Actions follow the privacy model of the person using your app. People can decide to share the actions they've taken on your app with 'Everyone' or with 'Friends' or keep them private to themselves. When configuring your action, you determine the default privacy level. People using the app can choose to override that default privacy level with any privacy level that's more restricted. The person cannot choose a privacy level that's more open, which might be important if you are building an app where you need to ensure a minimum level of privacy.

Learn More

  • Get started with a sample web app that can publish Open Graph stories.
  • See how companies have use Open Graph to build successful games, sites and apps in ourshowcase.
Was this document helpful?