The Open Graph helps people tell stories about their lives with the apps they use. Through these stories, apps become part of a user's identity on their timeline. Open Graph stories also appear in news feed and ticker and are eligible for more engaging presentation formats and greater distribution.
Because of this close relationship between apps and users, Open Graph integrations must work in ways that meet user expectations. You must give users proper notice and controls. The content your app publishes has to be accurate, meaningful and well-structured. To ensure apps do this well, we defined a series of guidelines and review all actions to make sure they meet our requirements.
Please note that we are not approving your app, just your use of the Open Graph. We perform these reviews to make sure people have a consistent, high-quality experience on Facebook, regardless of which apps they use. If you need to make changes to your submissions before your actions are approved, we’ll explain why and give you suggestions for what to change. Once you make the changes, you can resubmit your action for approval.
This is a living document and will change as we and 3rd party developers understand more about how users interact with the Open Graph.
Open Graph is designed to help people express who they are with the apps they use. Your Open Graph actions and objects should create quality experiences for your users.
Your stories should only publish when users perform actions in your app — not when a user installs or joins the app or when a friend takes an action. This is true for all action types except for common follows action.
Don't Surprise or Confuse People
Your action should make contextual and grammatical sense and should accurately represent the action the user took.
Don't use hateful, sexually explicit or misleading words.
Custom buttons for actions should be consistent with the look and feel of your app and not use Facebook branding, functionality or interface elements.
If your custom action is triggered as users browse, view, discover or otherwise look at content within your site, it is considered content consumption and is not allowed. For example, we will no longer approve custom actions for content consumption, such as “Rebecca viewed sandals,” even in cases where a person first clicks a button.
|User browses content in the app and clicks a "want" button. A story is published back to the user's timeline and to the news feed of friends that the person "wants" content.||Yes||There are clear controls to share back to Facebook. Action ("want") is not related to content consumption.|
|User completes a level in a game and a story is published back to the user's timeline and to the news feed of friends that the person "won" the match.||Yes||User performed action that triggered story. Action ("win") is not related to content consumption.|
|User browses content in the app. A story is automatically published back to the user's timeline and to the news feed of friends that the person "browsed" content.||No||Automatically publishes when the user viewed the content on the site. Action ("browse") refers to content consumption.|
|User browses content in the app and clicks a "browse" button. A story is published back to the user's timeline and to the news feed of friends that the person "browsed" content.||No||Custom action for content consumption (“browse”) could confuse people into thinking they unintentionally shared something.|
We only allow apps that use our common actions to publish content consumption actions. This allows us to ensure a good user experience by specializing story formats and setting clear user expectations. (ex: "reading an article" or "watching a video").
Here are some things we are not a fan of:
To submit a common action, you must first publish the action from your app or by using the Graph API explorer. It will then appear in the Review Status section of the App Dashboard with the 'submit' button enabled.
In the review status section, click on "submit".
Many Common Action have specific guidelines for approval. You can review them on the main open graph landing page.
When submitting a common action, you will need to:
Click on "Stories" in the left-hand navigation bar under Open Graph and click "Create a New Story" to get started.
Create a new action type and a new object type (or select from an existing object type). Please be sure that your actions don't replicate functionality of a common action.
Your actions should meet the following criteria:
Use clear, simple wording for actions (ex: “playing” is better than “has been playing”). We will not approve submissions if they're overly descriptive or convoluted.
If your action requires a preposition (ex: "vote for" or "comment on"), please attach the appropriate preposition to your action tenses.
You should configure story text for all tenses. Though your actions will be rendered with the preferred tense most of the time, Facebook will render other tenses when necessary.
Spelling and Grammar
Always double check your spelling and make sure the story text is grammatically correct.
Submit your actions, objects and usage instructions in English. Your actions and objects are translated separately in the Localize tab of the App Dashboard.
To edit tenses and attachments, scroll down to the Stories section located below the General Properties section, and click on the "Edit Tenses" or "Edit Attachments"buttons. Attachments show how your action should be presented visually in NewsFeed and Timeline. You may configure the story as either an item or map layout. You can also add captions.
If you want to enable optional capabilities for your actions, after you have created the action, navigate to the Open Graph section in the left-hand navigation bar, click on Types, then look for the "Action Types" section located below Object Types section. Click on a verb to edit it.
Before you can submit an action for review, you must publish it from within your app with the test user created during the submission process called the Open Graph Preview User. Do not submit your app for approval until you can successfully publish actions to the timeline of this test user.
To review your action, you must provide step-by-step instructions for how this action is triggered within your app. These instructions will be used by the team evaluating your app. You are also strongly encouraged to upload screenshots of each step within the app and a screenshot of the story as it appears on a user's timeline, as this significantly expedites the review time. This is especially helpful if your website is not in English.
Based on the additional properties you specified on the Action Type definition screen, you may be asked to provide repro steps to trigger optional capabilities.
Each action property has specific requirements and guidelines, so please review them before submitting:
This page displays a summary of your submission. Review the action summary and click Submit for Approval. After confirming that your submission has been added to the review queue, you will see a dialog letting you know that submissions are reviewed, on average, within 3 business days.
Once a story is submitted, the review status section will indicate a pending status next to that story.
Once an Open Graph action is reviewed, the App Dashboard will update the resulting status to say either Approved or Changes Needed in the Open Graph Dashboard and on the Review Status section. At any time, you may cancel your pending request.
All developers on your app will receive a developer alert when action submissions are made, approved, or returned for changes.
To help get your action reviewed in a timely manner, please make sure your submission follows all of the guidelines listed in this document. Here are a few common mistakes that will require changes to your submission before it is approved:
Only use action tagging if all tagged users are performing an action.
Check your grammar to make sure everything is spelled and conjugated correctly.
If your action needs a preposition to make grammatical sense, add it to your configuration (ex: "vote for", "comment on", and "wish for").
Your common like action should not use a “thumbs up” image of any kind or otherwise emulate the design of Facebook’s Like buttons.
We can't approve your action without adequate usage instructions and a working test environment. Make sure to publish your action to the Open Graph Preview User’s timeline to verify it in your test environment before submission.
We look at your usage instructions to test your action/object pair. We are looking to see that it is functional, adheres to our policies and follows our Open Graph guidelines.
Steps to Reproduce Your Action must be:
Create step-by-step instructions so we can trigger the action. Include all relevant links and test user credentials, so we can reproduce your action and additional properties.
Outline how your action and objects relate. If you have more than one object, explain how your action relates to each of the objects.
Example Steps to Reproduce a custom action:
1. Go to www.mytestapp.com. 2. Click the Create Account button in the upper right corner. 3. Click the Connect Using Facebook link. 4. Click on any style. This triggers the snap action. 5. Click the Comment button. 6. Write something. 7. Click the Add Comment button.
The next example shows good instructions for the common action: read. In this example, the submitter helped us follow along by numbering the instructions that show a complete sequence, and including steps to delete a shared story or turn off sharing.
1. Go to www.mytestnews.com. 2. Click the Connect Using Facebook link. 3. Click an article link. The common action publishes to the timeline 10 seconds after you start reading the article. 4. To remove an article action that was published to your timeline, click the Unshare link below the article title. 5. You can control what is shared with the on/off toggle beside the Unshare link.
Common characteristics of poor instructions:
> (User/Pass) Open Graph Preview User / 1234567 http://dev.mytestapp.com/test1/facebook Token: AAADowZB8bMiABAPtIE30SQZBPwTX91wzEoV5fMA5ZCjOn5QUMj0XlT waW1fyjt9jj2rMry8h5BwLugiaf2l5H5E6ZCGRwv9Kv6ibZCzGrSZA2ohYCYok7L Action ID: 12345678910111
> This app is an online newsletter. We have integrated Open Graph features to let users read articles through their Facebook account. Users read articles and the action publishes to timeline.
2. Include all necessary information in your usage instructions.
> Please refer to steps in the previous "Run" action ticket.
3. Provide instructions for all functionality. Open Graph supports the use of many additional functions, including action links, tagging people, tagging locations and user-generated photos. So you need to provide instructions for all that are applicable.
1. Go to www.mytestapp.com. 2. Click the Connect Using Facebook link. 3. Go to a recipe page. 4. Click the "I'm making this!" button. The action is published on your timeline.
To tag friends who are cooking with you:
To add a custom message to the recipe:
To add a photo of the recipe you’re making:
We need to test your app in an environment a real user would experience. With the exception of Native Mobile Apps (see more below), please do not submit apps in development until the testing environment represents the real user experience.
Test your action with the test user created during the submission process called Open Graph Preview User. Do not submit your app for approval until you can publish actions to the timeline of this test user with your reproduction steps.
Links and Credentials
Include all necessary passwords, test user credentials and links to staging servers that we need to test your action. Test users cannot like pages, so please don't place your app behind a like gate.
Native Mobile Apps
Your actions are most likely not live in the version of your app that's available in the App Store or Google Play. Please upload screenshots with your submission that document the complete user flow for your integration, including all of your actions, additional properties and Open Graph stories on timeline.
Your Open Graph actions are most likely difficult to trigger due to the advanced game play needed to reproduce the action. Please upload screenshots with your submission that document the complete user flow for your integration, including all of your actions, additional properties and Open Graph stories on timeline.
When submitting app screenshots, please show us the entire flow. If you're requesting an action property for your native mobile app or game submission, include images that show how the user triggers the property (ex: for User Messages, include a screenshot of the comment field). Please also include the story as it appears on a user's timeline.
If you have received a notification that your action requires changes, you will need to make the requested changes and click Save. At the top of the page you will see that your action changes have been saved and that they have yet to be submitted for review. Click on the Open Graph section and click submit for your action. At any time, you may cancel your pending request.
Once your action is approved, you can also resubmit to request additional properties. These changes will not affect the status of your already live submission. When submitting for approval your action will be listed as Active with pending changes. The Active status of your action will not change throughout the resubmission process.