Watch Next guidelines for app developers

App developers must follow these guidelines when inserting content into the Watch Next channel.

What types of content should be included in the Watch Next channel?

Your app should limit its programmatic additions to traditional movies and TV shows. Avoid adding clips and other short form content.

Unfinished movies

Add unfinished movies (as defined below) to the Watch Next channel using TYPE_MOVIE.

  • The user has "started" a movie if they've watched more than 3% or 2 minutes, whichever timestamp is earlier.
  • The user has "finished" a movie if the end credits start. In this case, do not add it to the Watch Next channel. You can determine this state using a technology that auto-detects the end credits, or use an approximation based on the content length.

Unfinished TV episodes

Add unfinished episodes (as defined below) to the Watch Next channel using TYPE_TV_EPISODE.

  • The user has "started" an episode if they've watched more than 3 minutes.
  • The user has "finished" an episode if the end credits start. In this case, do not add it to the Watch Next channel. You can determine this state using a technology to auto-detect end credits, or use an approximation based on the content length (for example, less than 3 minutes remaining in an episode).

Handling new TV episodes and next TV episodes

Add new episodes and next episodes (as defined below) to the Watch Next channel using TYPE_TV_EPISODE.

  • The user has "started" a series if they've watched more than 3 minutes (or 1 minute after the introduction completes) of any episode in the series.
  • If the user has "started" a series and has "finished" an episode, and the next episode in the series is available in your service, add this next episode to the Watch Next channel using WATCH_NEXT_TYPE_NEXT.
  • If the user has "started" a series, is fully caught up (that is, watched all available episodes up to and including the latest one), and a new season or episode becomes available at a later date, add this new episode to the Watch Next channel using WATCH_NEXT_TYPE_NEW. Add the new episode no matter how far in the future the episode becomes available (for example, after a year or more).

When should you add an item to the Watch Next channel?

You should add unfinished content and new episodes of a previously-viewed series to the Watch Next channel according to the following guidelines.

Unfinished content

Whenever a user has an unfinished piece of content, add that piece to the Watch Next channel immediately when either of the following occur:

  • The user exits the app on Android TV.
  • The user pauses or stops playback for a piece of content for greater than 5 minutes.

Publish any unfinished content from the above scenarios immediately (with a maximum latency of 5 seconds). For example, from the time the user exits the Android TV app, the app should publish any unfinished items using the Watch Next API within 5 seconds.

Publish any unfinished content to Android TV using the Watch Next API regardless of where the viewing occurred. For example, if the user watches a movie in their Chrome browser and pauses it, then the app on the Android TV should publish the unfinished content to the Android TV immediately (with a maximum latency of 5 seconds).

New episodes

Add a WATCH_NEXT_TYPE_NEW item immediately when the following are all true:

  • The new episode is available on your service.
  • The user has completed the previous episode.
  • The user is entitled to watch the new episode.

Add the new episode no matter how far in the future the episode becomes available (for example, after a year or more).

Eligibility of content and UI updates

The user should have interacted with the content within your app for the content to be eligible to be published to the Watch Next channel.

Do not update all items in the Play Next row when any one item changes. Only update the item which the user has interacted with since the last update.

What data should you include for a Watch Next item?

You should include the following for each Watch Next item:

  • Watch Next Type
  • Last Playback Position
  • Duration
  • Last Engagement Time
  • Video Program attributes: In addition to the required attributes marked in the video program attributes table, the Content ID attribute must be set for every video program. The Content ID attribute must match the internal ID you provide in the Media Actions feed. This allows Android TV to reconcile the asset more effectively and provides a high-confidence feature to users.