Open Graph Review
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:
- Support for creating new objects will end in January 2017.
- Support for publishing existing objects will end October 2017.
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:
- Publish when people install or join an app
- Correspond to content consumption: look, view, browse, or discover
- Even if an app user clicks a view button, a story such as "Rebecca viewed sandals" would not be approved
- Misrepresent people's in-app actions and confuse users
- Clicking a "love" button should trigger a "love" story, not a "share" story
- Publish multiple times for one in-app action
- Fail to make contextual and grammatical sense
- Use complex actions and verbs
- Copy Facebook branding, functionality, or interface elements
Please note that app domains are not necessary to track installs or create Open Graph stories for mobile apps.
Submit for Review
When to Submit for Review
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:
- Create a new Open Graph story
- Edit an existing Open Graph story
Our team reviews your Open Graph stories to make sure they follow our principles.
Step 1: Create a New Action
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.
Step 2: Create a New Story
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.
Step 3: Publish a Test Action
Before submitting for review, you must publish the Open Graph story from within your app with the test user.
Step 4: Provide Usage Instructions and Screenshots
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.
Step 5: Review and Submit for Approval
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.
Step 6: Understanding Open Graph Submission Feedback
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:
- Listing a website that does not use Facebook Login. Please note that we review all platforms listed in App Settings for Facebook integration.
- The "taste" action did not publish on any of the listed platforms (Website & iOS). This rejection means that the reviewer followed your instructions and screenshots, but could not publish "taste" on Facebook. Make sure to check your code and staging credentials. Only submit when you can successfully and consistently publish the Open Graph story.
See more about understanding submission feedback here.
Additional Capability Guidelines
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.
- Action tagging appends "- with Friend" to the Open Graph story.
- Mention tagging allows your app's users to tag friends names within their user messages.
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.
- Explicit shares need to be optional and have a user-generated component. People must knowingly decide to share the action back to Facebook.
- A clear Facebook sharing control needs to be present for each and every explicit share (not in a separate settings area).
- A "clear Facebook sharing control" contains user education that the action will "Share to Facebook." Use the word "Facebook" or Facebook imagery (i.e. the Facebook icon) for the sharing control.
- We have one exception for games within the Facebook frame (canvas / page tab apps). In this case, the sharing control can simply say "Share" because the experience is already within the Facebook chrome.
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:
- A "Facebook" toggle that turns blue when marked and text that indicates the action is a "checkin"
- A checkbox w/adjacent messaging that marking it will "Post to Facebook"
- A Facebook logo button that turns blue when clicked and text that indicates the action will "share"
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.
Open Graph Language Guidelines
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.
Edit Tenses and Attachments
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.
Timeline Screenshot Guidelines
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.
- Show the Open Graph story as it appears on a test user's Facebook Timeline.
- Please do not edit the screenshot or submit a screenshot of the sample story view within the developer console.
Taking a Timeline Screenshot:
- Timeline screenshots need to show all additional properties.
- Navigate to your test user's "Recent Activity" log.
- Find the Activity Log entry of the published Open Graph story.
- Hover beneath the story text and click the time stamp.
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.