The Open Graph API allows 3rd party apps to integrate deeply with Facebook. Your app can use the Open Graph API to tell well-structured, custom stories on Facebook. Open Graph stories can increase your app's engagement, distribution, and growth.
We review your app's Open Graph stories to ensure a consistent, high-quality experience on Facebook. Please remember that all platforms in your app Settings tab go through review.
Custom Open Graph stories are deprecated in Graph API 2.8. Graph API 2.7 and lower will support custom Open Graph stories according to the following schedule:
You may use Common actions that do not need review. More info here.
Open Graph stories must accurately represent people's in-app actions and publish after people perform actions within your app. Using a social plugin, such as the like button, does not require review.
When a person actively decides to share their actions, request the explicit share property. Explicitly shared Open Graph stories create a better experience for your app's users and also receive increased distribution on Facebook. All stories should be high-quality.
Your Open Graph story cannot:
Please note that app domains are not necessary to track installs or create Open Graph stories for mobile apps.
Your Open Graph actions will only be visible to the public after they have been approved. You will need to submit for review every time you:
Our team reviews your Open Graph stories to make sure they follow our principles.
Click Open Graph >> Action Type >> and the Add Action Type button.
We encourage you to use common actions when possible. Common action verbs (i.e. "like") will appear in the dropdown menu as you type them. For non-common actions, you must type in the complete word and press save.
After creating an action type, you can also configure additional capabilities. Please review the specific requirements for additional capabilities.
Click Stories >> and the Add Custom Story button.
Your action type should already be visible in the menu. If not, type and add a new action type. Repeat these steps for an object type. After selecting both an action type and an object type, press create.
Before submitting for review, you must publish the Open Graph story from within your app with the test user.
Ensure that you have filled out the necessary fields in App Details.
For Open Graph stories, we recreate your app's user experience. As a result, we require step-by-step usage instructions and screenshots: 2 in-app screenshots & 1 timeline screenshot of the Open Graph story.
Click Start a Submission >> Add items >> and Submit for Approval.
After your submission goes through successfully, a dialog stating that submissions are reviewed in 3 business days will appear.
The App Review page will show your submission's latest results. To view detailed feedback for your Open Graph stories, click the hyperlinked text or navigate to the Open Graph tab.
This example Open Graph action was rejected for:
See more about understanding submission feedback here.
Navigate to the Open Graph tab, click Action Types, and then click the verb that you want additional capabilities for.
For these additional capabilities, please mark the appropriate checkbox, save changes, and submit within the App Review tab.
Please include all necessary instructions, screenshots, and test user credentials for triggering these capabilities.
There may be scenarios where your app's users want to tag a friend. This tagging capability comes in two forms. One scenario is if the user takes an action with the friend (i.e. cooks a pizza with someone), and the other scenario is when the user simply wants to mention a friend (i.e. "Hey John Smith, let's make a pizza next time"). If you choose to choose to support both action and mention tags, clearly distinguish the two different use cases in your submission.
Users must perform the action with the person they tag. In addition, your app's tag feature must clearly indicate how to tag and untag. All tags must be manually added by your app's user.
The above example provides the option to tag one of my Facebook friends, indicates when I have tagged a friend (with a checkmark), and also provides the option to remove the tag (either by unselecting the checkmark or pressing "remove all").
To request action tags, please mark the "tags" capability.
Similar to the action tag requirement, the mention tag feature must clearly indicate how to tag and untag someone. In addition, since mention tags appear in the user message field, your app cannot pre-fill user messages with text or tags.
To request mention tags, please mark the "tags" and "user messages" capability.
The user messages additional property allows users to attach personalized messages to their in-app experiences.
Users must personally write these messages. Even if users can control (edit or delete) the message content, your app cannot pre-fill user messages.
The above example demonstrates how someone would have full control over the user messages property.
To request, please mark the "user messages" capability.
The photos additional property allows users to attach photos to their in-app experience.
Users must take these photos with an actual camera. All photos must be original.
The above example demonstrates how the app's photos are original and taken with a camera.
To request, please mark the "user-generated photos" capability.
The place additional property allows users to attach locations to your app's Open Graph story.
Users must be at the physical location when the action occurs. For example, we do not allow stories where users have not completed the action in the location: "Peter wants to cook a recipe on Recipe Box - in New York, NY."
To request, please mark the "place" capability.
Explicit shares can be used for a variety of actions such as posting a photo, checking in at a restaurant, sharing a song, or other key sharable moments. The important thing is that people decide to share their in-app experience, and the sharing mechanism is clear and conspicuous. Due to the increased intent behind explicitly shared stories, these stories achieve greater distribution.
Some examples of clear Facebook sharing controls are below. All controls would need to be present for every explicit share and accompanied with the appropriate context:
To request, navigate to the Open Graph tab, click Action Types, and then click the verb that you want additional capabilities for. Mark the "explicitly shared" capability.
Your Open Graph stories must meet the following criteria.
English Submit your actions, objects, and usage instructions in English. Your actions and objects are translated separately in the Localize tab.
Spelling and Grammar Always double check your spelling and grammar.
Simple, Clear Wording Use clear, simple wording for actions (ex: “playing” instead of “has been playing”). Only conjugate one verb for each action type. Do not include words of temporal relevance for verb conjugations (ex: "has," "had," "just").
Prepositions If your action requires a preposition (ex: "vote for" or "comment on"), please attach the appropriate preposition to your action tenses by editing each each tense.
Click Open Graph >> Stories >> and the Edit Tenses or Edit Attachments buttons.
Attachments show how your action will display visually in News Feed and Timeline. You can configure the story as an item or map layout, and add captions.
After creating your action type, tenses are automatically conjugated. We recommend that you only edit tenses to include a necessary preposition or change the present tense from "is tasting" to "tastes."
After conjugating a single verb and keeping your story's objects simple, you can add complexity by editing each flexible story. In this example, the "one to one" story is edited to include adjectives.
If you make and save changes to Open Graph stories, please make sure to submit for approval.
The Timeline Screenshot needs to show your Open Graph story publishing on Facebook, with all requested additional properties. Keep in mind, if you request additional properties, you will need to include images that show how to trigger the property. For instance, if you apply for user messages, you will need to include a screenshot of the comment field within your app.
Taking a Timeline Screenshot:
In the screenshot of the Activity Log, we see the "review" action, but not the associated user message.
By following step 4 (clicking on the time stamp), we see the Open Graph story with its additional properties. In this case, we see the "review" action with the user messages property.
Please follow the steps to capture a full Timeline screenshot, as we need to see all additional properties publishing properly with the Open Graph story.
Use the following checklist to ensure your app follows our review guidelines:
The Story can be told with Open Graph. Use common actions if you can. Only create a custom action if we do not provide it. We do not approve the following actions: listen, browse, discover, view, join, register, and any non-English actions
Open Graph action should be different from Social Plugins. Your Like and Comment action should be different from the Like Social Plugin and Comment Social Plugin. The Social Plugins already write to Open Graph and do not need to be submitted for review.
Use an Open Graph Test User to generate stories used during review. You need to submit two screenshots of the in-app user flow, as well as the Open Graph story appearing on a person’s Timeline.