Built-in Action Types
Facebook has defined a set of common actions for use in your apps. These Built-in Actions are designed to work with specific Built-in Objects. The following Built-in Action-Object pairs are available:
In order to use a Built-in Action in your app, you will need to add the particular Built-in Action to your app and submit its use for approval through the App Dashboard. In addition since built-in actions show up in a variety places within Facebook, the review process will be more detailed.
Listen (music.listens)
In order to access the built-in Listen action, you must have the appropriate relationships in place with rights owners. We are slowly increasing the number of developers that can leverage the built-in Listen action. If you are interested, please complete this form.
Read (news.reads)
For developers building apps in the News vertical, we have created the built-in Read action that can only refer to the built-in Article object type. Publication of Read actions can be enabled by registering this built-in action for your app through the App Dashboard. As a convenience, the built-in Article object will be automatically added to your app as well.
| Property Name | Description | Type |
| Start Time | When the read action begins | DateTime |
| End Time | When the read action finishes | DateTime |
| Article | A reference (URL) to an article object | article |
For other objects with readable-content such as the built-in Book and Blog object types or your own custom object types, you should define a custom action for a user's read actions on these objects.
Requirements
Prior to submitting the use of the built-in Read action by your app for approval, please ensure that your app meets all of the following requirements:
Point to Article Content
When publishing Read actions, the connected object should have actual article content. In most cases this should not be an issue if you own the content. However, a scenario that would not be approved would be if a Read was published for simply clicking on a link to article content.
Publish When Reading
Read actions should only be published when there is a strong indication that the user is actually reading an article. A few examples of when the publication of a Read action should be delayed:
- A multi-page article where a user has to click "Next" - the action should only be published when the user is at the last page.
- Article content that only displays a few preview sentences and asks a user to click for more to read - the action should only be published when the user gets to the full content.
To publish a built-in Read action on a built-in Article object to Open Graph, invoke the following call
POST https://graph.facebook.com/me/news.reads?article=[article object URL]
If the publish is successful, the return value of the call is an action instance id that represents the just published built-in Read action.
Publish Awareness
The user should be aware that publishing to Facebook is occurring. This could manifest in many different ways but ultimately the user should not be surprised that Read actions are being published.
As part of the user experience of your Open Graph-enabled app, provide the following capabilities to your users:
- A clear way for users to control the publishing of their actions back to Open Graph. In the example News app below, a clear "On/Off" switch is provided that applies to all future Read actions within the app. When a user toggles the switch to "Off", this prevents the app from publishing Read actions from that point on. Toggling the switch back to "On" reenables the publishing.
- A clear way for users to remove articles that were just shared through your app. In the example below, a user can easily remove a recent article that was shared as a result of a Read action that was published by the app.
DELETE https://graph.facebook.com/[read action instance id]
The Read action instance id is returned by the previous call that successfully published the Read action to Open Graph. You are also able to search for the corresponding id if you have the appropriate permissions to query a user's list of published built-in Read actions by invoking the following callGET https://graph.facebook.com/me/news.reads
Watch (video.watches)
For developers building video apps, we have created a common Watch action. This action can only refer to a built-in video-type object such as Movie, TV Show, TV Episode or Video. As a convenience, these built-in video-type objects are automatically added when you register the built-in Watch action for your app.
If you are connecting Watch to other objects outside of the ones we've defined, please use a custom open graph watch action for now.
| Property Name | Description | Type |
| Start Time | When the watch action begins | DateTime |
| End Time | When the watch action finishes | DateTime |
| Movie | A reference (URL) to a video.movie object | video.movie |
| TV Show | A reference (URL) to a video.tv_show object | video.tv_show |
| Episode | A reference (URL) to a video.episode object | video.episode |
| Video | A reference (URL) to a video.other object | video.other |
Requirements
Prior to submitting the use of the built-in Watch action by your app for approval, please ensure that your app meets all of the following requirements:
Publish When Watching
When a user starts watching any video-based content through your app, publish a story to Open Graph about the video.watches action with video as a reference to the built-in video-type object content
POST https://graph.facebook.com/me/video.watches?video=[video-type content url]
You can also supply values for optional action properties such as start_time to specify when a user started watching a movie and expires_in to specify the length of a movie in seconds. By default, start_time will be set to the publish time of the Open Graph story about the activity, and expires_in will be set to the duration of the video-type object as specified in its Open Graph object markup.
For example, if a user watched a Movie for two hours on May 5th, 2011, this activity would be published to Open Graph as
POST /me/video.watches?
video=[movie object content url]&
created_time=2011-05-05T13:22&
expires_in=7200
This call will return an id that represents this particular instance of a movie watching activity.
If the user watches more than 50% of a video, but does not complete it, the action instance should be updated to reflect that the user has stopped watching by updating expires_in to the length of time the video was actually watched:
POST https://graph.facebook.com/[watch action instance id]?expires_in=7054
When a user watches less than 50% of a video, or if a user removes a watch activity from your app/site, you should also remove the corresponding action instance that was published to Open Graph by invoking the following call
DELETE https://graph.facebook.com/[watch action instance id]
You are also able to search for the corresponding action instance id if you have the appropriate permissions to query a user's list of published built-in Watch actions by invoking the following call
GET https://graph.facebook.com/me/video.watches
Publish Awareness
You will comply with the Video Privacy Protection Act (VPPA), and obtain any opt-in consent necessary from users so that user data subject to the VPPA may be shared on Facebook. You will represent that any disclosure to us will not be incidental to the ordinary course of your business.
You must give the user clear, ongoing, and in-context messaging that their watch actions will be published on Facebook.
- Clear - a plain, easy to understand messaging to users
- Ongoing - the messaging should appear every time a user watches a video, not just the first time (e.g., on the page where the user watches the video)
- In-context - the messaging should be visibly close to the video that the user is watching
Updated on Friday