For developers building video apps, Facebook provides a common Open Graph
This action and associated object types are automatically added to the App Dashboard when you use the action for the first time.
This document covers the following topics:
You can find platform-specific code samples on how to create, read, update, or delete a
watch action in the API Reference Guide.
Explicitly Sharing Watch Actions
An app can enable people to explicitly share their
watch actions. This means that the person clearly intends to share their watching activity on Facebook (for example, by clicking on a button). To explicitly share, the
fb:explicitly_shared parameter must be set to
When a person starts watching any video-based content through your app, and has viewed that particular video content for at least 10 seconds, publish a story to Open Graph about the
video.watches action with
video as a reference to the common 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 person 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 object type.
For example, if a person watched a
movie for two hours on February 20th, 2013, this activity would be published to Open Graph as:
POST /me/video.watches? video=[movie object content url]& created_time=2013-02-20T13:22& expires_in=7200
This call will return an id that represents this particular instance of a movie watching activity.
If the person watches more than 50% of a video, but does not complete it, the action instance should be updated to reflect that the person 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 person watches less than 50% of a video, or if a person 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]
Before you submit the use of
video.watches action by your app for approval, confirm your app meets all of the following requirements:
Properly Configured Objects
This action can only refer to the following objects:
video.other. As a convenience, these common video-type objects are automatically added when you register the common
watch action for your app. Submission for custom
watch actions is no longer accepted.
Please note that the
video.movie object is reserved only for full-length, feature films (i.e. not to be used with movie trailers, movie clips, user-generated video content, etc.).
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 will also always provide users with a clear, ongoing, and in-context message that their watch actions will be published to Facebook.
- Clear - a plain, easy-to-understand informative message to users
- Ongoing - this message should appear every time a user watches a video (e.g., on the page where the user watches the video)
- In-context - this message should be visibly close to the video that the user is watching
New User Education
If you plan on using an in-line control, your app needs to explain to users how the control works, including the fact that the app will publish watch actions to the user's timeline when sharing is enabled. If your app is streaming video, watch actions may only be published after the user has watched at least 10 seconds of the video content.
Finally, provide users with the ability to remove any video stories that your app publishes to Open Graph, and the ability to turn this sharing on or off at any time. The selection or choice made by users on their sharing preferences should be persisted.
If your watch action is not triggered by a user clicking a "play" button in a video player, you must make it clear to to the user that you will be publishing a watch story.