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:
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:
This document outlines our guidelines and submission criteria. This document may evolve as we continue to learn how people interact with the Graph API.
Your story cannot:
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.
You can remove a platform by visiting the Settings section of your App Dashboard:
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).
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.
Before you can submit for review, you'll have to publish the story from within your app with a test user.
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.
Click Start a Submission >> Add Items >> and Submit for Approval.
Submissions are reviewed, on average, within 3 business days.
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:
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 your actions, objects, and usage instructions in English. Your actions and objects are translated separately in the Localize tab.
Always double check your spelling and grammar.
Use clear, simple wording for actions (ex: “playing” instead of “has been playing”). Only conjugate one verb for each action type.
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:
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.
Taking a Timeline Screenshot:
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.
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
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.
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.
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.
Some examples of clear Facebook sharing controls are below. All controls would need to be present for each and every explicit share:
To request, please mark the "explicitly shared" capability.
Use the following checklist to ensure your app follows our review guidelines:
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.