Custom Stories Submission Process
The Open Graph API helps people tell Custom Stories about their lives with the apps they use. Through these stories, apps become part of a user's identity on their timeline. Custom 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, Custom Stories 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 API. 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 API.
- Open Graph Principles
- Submitting Common Actions for Review
- Submitting Stories for Review
- Checking On Your Pending Submission's Status
- Best Practices for Open Graph Submissions
- How We Use Instructions When Reviewing Submissions
- Resubmitting Actions for Review
- Guidelines for Action Capabilities
- Native Mobile Apps Submission Criteria
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 followsaction.
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 followsaction.
Don't Surprise or Confuse People
Your action should make contextual and grammatical sense and should accurately represent the action the user took.
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.
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.
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.
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 that make for bad user experiences:
- 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.
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.
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.
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.
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.
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 and Screenshots
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 required to upload at least two screenshots of each step within the app along with one screenshot of the story as it appears on a user's timeline.
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 Statussection. 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.
Best Practices for Open Graph Submissions
Use the following checklist to ensure your application follows our review guidelines prior to submission:
 |
The Story can be told with Open Graph. You should use common actions if you can. You should only create a custom action if it’s not one we provide. We no longer approve the following 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 story as it appears on a person’s Timeline.
|
|
Open Graph action reflects what is performed within the app. The action type should reflect real experiences and should not surprise or confuse people using your app.
|
|
Grammar is correct and verbs are conjugated correctly. Ensure your story variation is structured correctly and makes comprehensive, grammatical sense.
|
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.
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.
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.
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.
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.
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 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.
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.
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.
Guidelines for Action Capabilities
If you request an optional capabilities when submitting your action for approval we will need to be able to reproduce it. Please include all necessary instructions and test user credentials in order to test the specified functionality.
Action Tagging
There may be scenarios where your users will want to indicate that they took an action with friends. We call this action tagging and it can be easily accomplished by specifying the tags optional parameter when publishing a story.
Requirements
For Open Graph actions the action tagging capability can only be used when both users are performing the action together. It cannot be used to mention other users. To decide which type of tagging to use, follow these rules:
- Action tagging should be used when you are performing the action with the tagged user, e.g. "Jessica ran a marathon - with John."
- Action tagging should NOT be used to mention other users, e.g."Jessica took a photo- with John." This would not be an appropriate use case because only one person took a photo.
- Mention tagging should be used to mention other users or send them a shout out, e.g. Open Graph story: "Jessica took a photo" User Message: "What a great marathon, John!"
The two stories are rendered differently: action tags append “- with John” to the story text, whereas mention tags place the hyperlinked name inline with the user message.
NOTE: To allow your users to mention friends and pages in the message parameter, please see themention tagging docs
Submit for Approval
Tagging requires additional approval before you can use it. Prior to submitting your action for approval in the App Dashboard be sure to configure an action's capabilities to support tagging in the Action Type definition screen.
Upon submitting, please include all necessary instructions and test user credentials in order to test the action tagging functionality within your app.
User Messages
Using the message parameter enables your users to write personalized messages attached to their actions. This allows users to create more meaningful stories about the content they are interacting with in your app. You can also use the message parameter to mention users and pages inline with the message (see mention tagging).
Requirements
User Messages can only be used when the user writes a personal message attached to the action. They cannot be pre-filled by the app, even if the user can control (edit or delete) the content.
Submit for Approval
User Messaging requires additional approval before you can use it. Prior to submitting your action for approval in the App Dashboard, be sure to configure an action's capabilities to support user messages in the Action Type definition screen.
Upon submitting, please include all necessary instructions and test user credentials in order to test the user message functionality within your app.
User Generated Photos
With the increasing number of users having access to mobile cameras, there is a growing need to be able to share and associate user-generated photos with open graph stories. Stories with attached user-generated photos will have all of the same functionality of standard stories, but will help accentuate the photos with a larger display in Ticker, Timeline, and News Feed.
Requirements
The User Generated Photos action capability can only be used if the photos are original and taken by a user with an actual camera.
Submit for Approval
To take advantage of the user generated photo functionality, developers must check the User Generated Photos box when creating their action in the Action Type definition screen. Upon submitting, please include all necessary instructions and test user credentials in order to test the user generated photos functionality within your app.
Upon submitting, please include all necessary instructions and test user credentials in order to test the user generated photos functionality within your app.
Place
Actions can be tagged with places by specifying the place optional parameter. The place is attached to the story and also highlighted on the user\'s Timeline map.
Requirements
You can only specify the place capability if the user is actually at the physical location at the time the action occurs. For example, do not create a story where the user has not yet completed the action in that location like, \'Peter wants to cook a recipe on Recipe Box - in New York, NY\'.
Submit for Approval
To take advantage of location tagging functionality, you should check the Place box when creating your action in the Action Type definition screen. We will only allow this feature to be enabled if the place represents the physical location where the user is located when the action occurs.
Upon submitting, please include all necessary instructions and test user credentials in order to test the location tagging functionality within your app.
Explicitly Shared
It is appropriate to use explicit sharing in cases where the user is making a conscious decision to share their experience back to Facebook in real time. It represents something they would've entered or uploaded into the Facebook composer for sharing.
Explicit sharing can happen through a variety of actions like posting a photo or adding a message to an action a user has taken. The important thing is that users clearly understand they are posting this action to Facebook at that time and that they have an in-line way to opt out.
Here are some examples of apps explicitly sharing content on Facebook:
Inappropriate Use
The following types of actions should not generally be labeled as explicitly shared:
- Actions that occur naturally in an app, such as listening, reading, watching, and using
- Lightweight social buttons, such as liking, loving, favoriting, and saving
- Low-signal activities that happen bulk, such as following, friending, and passing
- Functional parts of game play, such as playing, earning, building, and gifting
Requirements
Explicitly shared content needs to be optional for users to post and have a clear Facebook sharing control that's visible in every instance of sharing (not separate in a settings area). The content should have a user-generated component or the user needs to be taken out of the natural flow of the app in order to make a conscious decision to publish the story back to Facebook.
Submit for Approval
In order to use explicit actions in production, you must first define your action as an explicit action in our App Dashboard in the Action Type definition screen.
Upon submitting, please include all necessary instructions and test user credentials in order to test the explicit sharing functionality within your app.
Mention Tagging
When publishing an OG action with a user message, it is possible to mention friends and pages directly within the text of the message. We call this mention tagging, in contrast to action tagging which is used to tag people in the action itself.
Requirements
- Have a clear indicator of how to add a tag. For example, a specific "insert friend tag" icon or an auto drop-down menu when you type an @ prefix.
- Clearly indicate when a user has been tagged and provide a way to undo tags.
- If you support both action and mention tags, have a clear distinction between the two.
- Do not pre-fill the user message with text or tags. Users should input the message and tags themselves.
The message composer in your Facebook profile is a good example of a UI for both action and mention tagging. A dedicated button allows you to tag people whom you are with (note the hint text that appears when you click the button). Mention tagging, instead, is done through a drop-down menu to auto-complete your friend's name.
Submit for Approval
To use mention tags in your action, you need to define your action as using two capabilities: Tags and User Messages.
When selecting the Tags capability, upon submission, you must explain if you are using mention tags, action tags or both. You must also describe step-by-step how users can add/remove tags in your app.
Native Mobile Apps Submission Criteria
Seeing that your actions are most likely not live in the version of your app that is currently available in the App Store or Google Play, please upload screenshots or a screencast with your submission that document the complete user flow of your Open Graph integration. This includes how the user would trigger all actions and additional properties as well as the Open Graph stories published back to timeline.
Uploading Images/Video
You can upload screenshots directly in the submission tool. If you are submitting a video please paste a link to your screencast directly into the usage instructions field.
User Experience
Since we are reviewing your actions based on screenshots, we need to understand as much about the app user experience as possible. The additional materials you attach should contain both images of the complete in-app user flow and each action and additional property published to the timeline of your personal account or a test user account.
Images/Video Needed
Complete User Flow
Step-by-step images of how a user would trigger the action. Please explain the user experience in each of your screenshots to clarify the user flow of your app.
Actions and Optional Action Properties Published back to Timeline
The individual story posted back to timeline. We need to make sure the optional action properties within your app are functioning and adhere to our guidelines.
No comments:
Post a Comment