Understanding the Open Graph Submission Process
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 Principles
- Submitting Common Actions for Review
- Submitting Stories for Review
- Checking On Your Pending Submission's Status
- Common Submission Mistakes
- How We Use Instructions When Reviewing Submissions
- Resubmitting Actions for Review
Open Graph Principles
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.
We review every action based on four areas: User Experience, Usage Instructions, Language, and Test Environment.
User Experience
User-Initiated Actions
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.Appropriate Language
Don't use hateful, sexually explicit or misleading words.Branding
Custom buttons for actions should be consistent with the look and feel of your app and not use Facebook branding, functionality or interface elements.
Content Consumption
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.
| Scenario | Allowed? | Rationale |
| 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:
- Misleading or confusing users by publishing stories that do not accurately represent the action the user took within the app.
- Publishing custom content consumption actions as users browse, view, discover or otherwise look at content within your site.
- Posting multiple actions for the same real-world action. If you need to post multiple actions to generate the right timeline units, you must turn off feed stories for those actions (use the no_feed_story=1 parameter when publishing an action).
- Creating stories that don't make sense. (e.g. You would not drink computers).
- Violating our Community Standards.
- Using poor grammar
- Actions or objects that are extremely long or complex
Submitting Common Actions for Review
Step 1: Publish the Action
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.
Step 2: Submit the Action
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:
Submitting Stories for Review
Step 1: Create a New Story
Click on "Stories" in the left-hand navigation bar under Open Graph and click "Create a New Story" to get started.
Step 2: Create a New Action
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.
Action Guidelines
Your actions should meet the following criteria:
Simple
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.Prepositions
If your action requires a preposition (ex: "vote for" or "comment on"), please attach the appropriate preposition to your action tenses.Preferred 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.English
Submit your actions, objects and usage instructions in English. Your actions and objects are translated separately in the Localize tab of the App Dashboard.
Edit tenses and attachments
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.
Optional Capabilities
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.
Step 3: Publish a Test Action
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.
Step 4: Provide Usage Instructions
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.
Read How We Use Instructions When Reviewing Submissions
Step 5: Review Optional Capabilities
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:
Step 6: Review and Submit for Approval
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.
Checking On Your Pending Submission's Status
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.
Common Submission Mistakes
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:
Action Tagging
Only use action tagging if all tagged users are performing an action.Language Configuration
Check your grammar to make sure everything is spelled and conjugated correctly.Prepositions
If your action needs a preposition to make grammatical sense, add it to your configuration (ex: "vote for", "comment on", and "wish for").Like Branding
Your common like action should not use a “thumbs up” image of any kind or otherwise emulate the design of Facebook’s Like buttons.Common Like vs. Like Social Plugin
Understand the difference between the two types of integrations and make sure you are submitting your Like action as appropriate.Test Environment
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.
How We Use Instructions When Reviewing Submissions
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:
Clear
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.Descriptive
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:
- Too technical
- Too vague
- Summarize the app instead of including step-by-step instructions
- Reference instructions from other submissions
- Incomplete
Don't:
- Include instructions that are too technical and do not use natural language to explain a process. For example, the following instructions do not provide a sequence, explain what to expect or how to achieve the desired result, so Facebook reviewers would not approve them.
> (User/Pass) Open Graph Preview User / 1234567
http://dev.mytestapp.com/test1/facebook
Token: AAADowZB8bMiABAPtIE30SQZBPwTX91wzEoV5fMA5ZCjOn5QUMj0XlT waW1fyjt9jj2rMry8h5BwLugiaf2l5H5E6ZCGRwv9Kv6ibZCzGrSZA2ohYCYok7L
Action ID: 12345678910111
- Summarizes the overall purpose of the app, without providing step-by-step instructions to demonstrate the action. For example, the following instructions lack the necessary detailed steps.
> 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.
Do:
- Repeat instructions in all of your submissions as needed.
- Include what to click on and where to find buttons or links.
- Describe how the submitted action relates to all connected objects.
Don't:
- Reference other submissions in your instructions. Each submission needs instructions that provide a complete description on their own. For example, don’t use:
> 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.
Do:
- Write out specific instructions for tags, messages and user-generated photos. The following example gives a simple sequence to reproduce the action submission and related features. Steps 1-5 are entered when asked to provide trigger steps.
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:
- Click the plus sign below the "I'm making this!" button.
- Select friends.
To add a custom message to the recipe:
- Write a comment in the box below the “I’m making this!” button.
- Click the OK button.
To add a photo of the recipe you’re making:
- Click the Upload button.
- Select a photo of your food.
Test Environment
Real Environment
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.Published Actions
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.Game Actions
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.Screenshots
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.
Resubmitting Actions for Review
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.
Updated about a week ago