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.
Story Submission Process
The Graph API allows third-party apps to integrate deeply with Facebook. Your app can use the Graph API to share rich, structured stories on Facebook. These stories can increase your app's engagement, distribution, and growth.
We review your app's stories to ensure a consistent, high-quality experience on Facebook. Three important notes:
- All platforms listed in your App Settings go through review. Please do not list platforms without Facebook integration (i.e. websites without Facebook Login).
- Using a Social Plugin, such as the Like button, does not require review.
- For mobile apps, app domains are no longer needed to track installs or create stories.
This document outlines our guidelines and submission criteria. This document may evolve as we continue to learn how people interact with the Graph API.
- Always abide by our Community Standards, Platform Policies, and Ad Guidelines
- Stories must accurately represent people's in-app actions and only publish after people perform actions with your app
- Use the explicit share property when a person consciously decides to share their actions
- All stories should be high-quality and make contextual and grammatical sense
Your story cannot:
- Publish when people install or join an app
- Publish when people look at, view, browse or discover content
- Ex: Even if a user clicks a view button, we wouldn't approve the story "Sue viewed sandals"
- Misrepresent people's in-app actions or confuse users
- Publish multiple times for a single in-app action
- Copy Facebook branding, functionality, or interface elements
When you submit a story, we'll review it for all platforms listed in your App Settings. All platforms must integrate with Facebook and direct people to the expected platform.
- Canvas & Page Tab functionality must primarily remain within Facebook. Redirecting people off violates Policy 1.11.
- Please check the requirements for Canvas and Page Tab apps to make sure you submit for the appropriate platform.
- We don't accept Canvas pages that redirect to Page Tabs, or vice versa.
- Websites & mobile websites must use Facebook Login.
- Mobile website URLs must also begin with "m." and be specifically configured for mobile devices. Please do not use your Site URL for the Mobile Site URL field.
- Mobile apps (iOS, Android, and Windows) must use the latest Facebook SDK.
You can remove a platform by visiting the Settings section of your App Dashboard:
How to Submit for Review
We review stories for all the platforms listed in the Settings section of your App Dashboard. These platforms must integrate with Facebook and direct people to the expected platform. Please do not submit URLs that redirect people to different platforms (ex: a Facebook canvas page URL that redirects to a Facebook Page Tab).
Step 1: Define Actions and Objects
Before you can publish stories, you'll need to choose an action from our list of actions.
You'll also need to define objects for your app by adding Open Graph tags to the HTML markup for your web content. You can find the full list of action and object types in this reference doc.
When you use pre-defined actions and objects, you can start publishing them without having to add them to the Open Graph section of your App Dashboard.
Step 2: Publish a Test Action
Before you can submit for review, you'll have to publish the story from within your app with a test user.
Step 3: Provide Usage Instructions and Screenshots
In order to test your story, we need to be able to recreate your app's user experience. To do this, we require step-by-step usage instructions and screenshots of the published story.
Step 4: Review and Submit for Approval
Click Start a Submission >> Add Items >> and Submit for Approval.
Submissions are reviewed, on average, within 3 business days.
Step 5: Understanding Submission Feedback
All of your app's developers will receive a developer alert when submissions are made, approved, or returned for changes.
In the above example, the story was rejected for:
- Listing a website that doesn't use Facebook Login in App Settings.
- The "taste" action failed to 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 story.
For unapproved stories or platforms, you will need to make the requested changes, click Save, and create another submission in App Review. You can cancel a pending submission at any time.
Your stories must meet the following criteria.
Submit in English
Submit your actions, objects, and usage instructions in English. Your actions and objects are translated separately in the Localize tab.
Use Proper Spelling and Grammar
Always double check your spelling and grammar.
Use Simple, Clear Wording
Use clear, simple wording for actions (ex: “playing” instead of “has been playing”). Only conjugate one verb for each action type.
Usage Instruction Guidelines
List your instructions in a step-by-step format so that we can reproduce your action and additional properties. Please make sure that you do not:
- Reference instructions from other submissions
- Summarize what your app does in place of instructions
- Provide technical details of how your APIs work
Example Usage Instructions (for a "read" action):
1. Go to www.mytestapp.com. 2. Click the Connect Using Facebook link. 3. Go to a book page. 4. Click the "I'm reading this!" button. The "read" action is published on your timeline.
Example Usage Instructions (for a "read" action w/additional properties):
To tag friends who are reading with you: 1. Click the plus sign below the "I'm reading this!" button. 2. Select friends. To add a custom message to the book: 1. Write a comment in the box below the “I’m reading this!” button. 2. Click the OK button. To add a photo of the book you're reading: 1. Click the Upload button. 2. Select a photo of your book.
Screenshot images need to represent your app's user flow for a specific story. The two screenshot minimum requirement should demonstrate usage instruction steps.
If you request additional properties, include images that show how the user triggers the property. For instance, if you apply for user messages, include a screenshot of the comment field within your app.
- Show the 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 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 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 the all additional properties publishing properly with the story.
Additional Capability Guidelines
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 story.
Mention tagging allows your app's users to tag friends names within their user messages.
Requirements for approval
- Your app must clearly indicate how to tag and untag friends
- The friend tagged in the story should actually be with the person taking the action. Otherwise, use mention tagging
- Tags must be manually added by the user
- Actions must be taken together ("John cooked a recipe with Mark") and not against each other ("Mark beat John in Recipe Challenge")
- Friend tagging shouldn't be used with an action in the future that has yet to occur
- Avoid mass tagging, which could resemble spam, by limiting the number of friends a user can tag
Here's an example of a acceptable use case. The app indicates when a friend has been tagged with a checkmark and provides the option to remove the tag.
To request action tags, enable the Tags capability in your App Dashboard under Open Graph > Action Types. Select an action to edit its additional capabilities.
- Enable both the user messages and tagging capabilities
- 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 friend has been tagged and provide a way to undo tags.
- If you support both action and mention tags, be sure there is a clear distinction between the two.
- Do not prefill the message parameter or the text field for it with anything. People should input the message and tag any friends themselves.
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.
The photos additional property allows users to attach photos to their in-app experience.
- Photos must be original and can only be those taken with a camera by the person who is publishing them
- Photos must be at least 480px by 480px in size
The above example demonstrates how the app's photos are original and taken with a camera.
The place additional property allows users to attach locations to your app's story.
Places should only be tagged when an action happens in the physical location. 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."
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 consciously decide to share their in-app experience. 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 make the conscious decision 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). Global sharing mechanisms are not allowed.
- A "clear Facebook sharing control" contains user education that the action will "Share to Facebook." You should use the word "Facebook" or Facebook imagery (i.e. the Facebook icon) to notify people that they are sharing their action back to Facebook.
- 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 platform.
Some examples of clear Facebook sharing controls are below. All controls would need to be present for each and every explicit share:
- A "Facebook" toggle that turns blue when marked
- A checkbox w/adjacent messaging that marking it will "Post to Facebook"
- A button with the Facebook logo that turns blue when on
To request, please mark the "explicitly shared" capability.
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 no longer approve the following actions:
- listen action
- content consumption: "browse," "discover," "view,", etc.
- actions triggered from joining or registering with an app
The 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 the Graph API and do not need to be submitted for review.
Use a 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 appearing on a person’s Timeline.
Actions should reflect 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.