Highlights in Inbox
Highlight your emails with important information and actions in Inbox by Gmail.
Friday, 10 July 2015
TV and Movie Watch Actions
Watch actions make Google Search an entry point for discovering and consuming TV shows and movies. Watch actions can appear in Google properties such as Knowledge Panel, enabling users to watch TV shows and movies from streaming services.
When a user searches for the name of a show on Google or on their mobile device, a Knowledge Panel "card" may appear prominently in the Search results. Watch actions in the card will use deep links to partner apps or web landing pages, bringing users directly from the Knowledge Panel to the specific episode or movie.
A deep link is a URL that points to a specific TV episode or movie from your inventory.
Integrating watch actions
Integrating watch actions is as straightforward as embedding schema.org markup in your landing page for the respective movie, TV episode, TV season, or TV season. Some example landing pages:
- Movie: http://www.example.com/movies/forrest_gump
- TV episode: http://www.example.com/tv/big_bang_theory/season1/episode1
- TV season: http://www.example.com/tv/big_bang_theory/season1
- TV series: http://www.example.com/tv/big_bang_theory
Movie and TV episode markup should contain WatchAction deep links to the full-length content.
TV season and TV series markup should contain ViewAction deep links to the respective landing page.
Markup format
You can embed data in a webpage using schema.org field names with the new JSON-LD data format. JSON-LD is easy to produce with many widely available JSON encoders. The
<script type="application/ld+json"> ... </script> block as shown in the example below may be placed in either the or region of the page that displays that video game. Either way, it won’t affect how your document appears in users’ web browsers.Important: Test your markup!
To test your markup, submit the HTML source of your marked-up web page to Google's structured data testing tool. If the tool reports
No structured data present, then you likely have a syntax error such as a spurious comma. Otherwise, if the tool reports that any required fields are missing, please repair the data and try again.Markup for movies and TV episodes
You can provide deep links for individal movies or television episodes using the following syntax.
For a streamlined user experience, deep links should support autoplay. On clicking a watch action link, your content should immediately start playing rather than directing the user to a landing page which requires subsequent clicks to initiate playback.
| Property | Type | Description |
|---|---|---|
@id (Recommended) | Text | Globally unique ID of the Movie or TVEpisode. The ID should be stable and not change over time. |
name (Required) | Text | Name of the Movie or TVEpisode. |
url | URL | URL to partner's landing page for the Movie or TVEpisode. |
description | Text | A synopsis of the work. Plot synopses are preferred to factual summaries. |
releasedEvent(Recommended) | PublicationEvent | Annotation for the original release date. |
releasedEvent.startDate(Recommended) | Date | Original broadcast/theatrical release date of the work, in ISO 8601 format. |
releasedEvent.location | Country | Annotation for the country of original release. |
releasedEvent.location.name | Text | Country in which the work was released on the above startDate. Use the 2-letter ISO 3166 country code. |
potentialAction(Required) | WatchAction | Annotation(s) for the full-length Movie or TVEpisode. See the "Markup for deep links" section below for details. |
hasPart | TVClip or Clip | Annotation(s) for short videos related to the Movie (use Clip) or TVEpisode (use TVClip). |
hasPart.description | Text | One of the following values:
|
hasPart.timeRequired | Text | Duration of the clip in ISO 8601 format, e.g. "PT2M5S" (2min 5sec). |
hasPart.potentialAction | WatchAction | Annotation(s) for the clip. See the "Markup for deep links" section below for details. |
image | ImageObject | Annotation(s) for images related to the work. Provide highest-resolution available. PNG and JPG preferred. |
image.height | Integer | Height of the image in pixels. |
image.width | Integer | Width of the image in pixels. |
image.url | URL | URL where the image can be fetched. |
sameAs | URL | URL to a reference web page that unambiguously identifies the work. Example: IMDB, Wikipedia. |
actor | Person | Annotation(s) for each cast member. |
actor.name | Text | Actor name. |
actor.sameAs | URL | URL to a reference web page that unambiguously identifies the actor. Example: IMDB, Wikipedia. |
director | Person | Annotation(s) of the director. |
director.name | Text | Director name. |
director.sameAs | URL | URL to a reference web page that unambiguously identifies the director. Example: IMDB, Wikipedia. |
Markup for TV seasons and TV series
In addition to TV episode markup, you can also markup TV seasons and TV series if:
- You have a distinct landing page for the TV season or series, separate from the episode landing pages.
- You have different watch action offers for users if they rent or purchase the entire TV season or series at once. Example: purchasing the 16-episode second season of The Walking Dead may cost $28 as opposed to purchasing individual episodes for $1.99 each.
Each season should have its own TVSeason annotation with the following properties.
| Property | Type | Description |
|---|---|---|
@id (Recommended) | Text | Globally unique ID of the TVSeason. The ID should be stable and not change over time. |
name | Text | Name of the TVSeason, if it differs from the series name. |
sameAs | URL | URL to a reference web page that unambiguously identifies the season. Example: IMDB, Wikipedia. |
url (Recommended) | URL | URL to partner's season landing page. |
potentialAction(Recommended) | ViewAction | Annotation(s) for the season. See the "Markup for deep links" section below for details. |
releasedEvent(Recommended) | PublicationEvent | Annotation for the original release date of the first episode of the season. |
releasedEvent.startDate(Recommended) | Date | Original broadcast date of the first episode of the season, in ISO 8601 format. |
releasedEvent.location | Country | Annotation for the country of original release. |
releasedEvent.location.name | Text | Country in which the season premiered on the above startDate. Use the 2-letter ISO 3166 country code. |
seasonNumber (Required) | Integer | Position of the season within an ordered group of seasons. |
partOfSeries (Required) | TVSeries | Annotation for the series of the season. |
partOfSeries.name (Required) | Text | Name of the TV series. |
partOfSeries.sameAs | URL | URL to a reference web page that unambiguously identifies the series. Example: IMDB, Wikipedia. |
Markup for deep links
The
potentialAction property of each Movie, TVEpisode, TVSeason, and TVSeries item should contain both the deep link(s) and any relevant condition(s), including:- The watch action is only available for a certain period.
- The watch action is only available for a certain region.
- The watch action requires a purchase or rental fee.
- The watch action requires a subscription.
- The watch action requires a subscription to an entity other than the partner, e.g. a cable subscription.
Properties
Each
potentialAction should be either a WatchAction (Movie or TVEpisode items) or ViewAction (TVSeason or TVSeries items) with the following properties.| Property | Type | Description |
|---|---|---|
target (Required) | URL | Deep link(s) to content. Examples:
|
expectsAcceptanceOf (Required) | Offer | Annotation(s) for the conditions of the deeplink. |
expectsAcceptanceOf.availabilityStarts(Required) | Date | Date after which the watch action is available, in ISO 8601 format. |
expectsAcceptanceOf.availabilityEnds(Required) | Date | Date after which the watch action is no longer available, in ISO 8601 format. |
expectsAcceptanceOf.eligibleRegion(Recommended) | Country | Countries in which the watch action is available. If unspecified, we expect the action is available everywhere except where denoted in potentialAction.. |
expectsAcceptanceOf.eligibleRegion.name(Recommended) | Text | Country name. Use the ISO 3166 country code. |
expectsAcceptanceOf.ineligibleRegion | Country | Countries in which the watch action is not available. If unspecified, we expect the action is available everywhere unless potentialAction. is specified. |
expectsAcceptanceOf.ineligibleRegion.name | Text | Country name. Use the ISO 3166 country code. |
expectsAcceptanceOf.category (Required) | Text | One of the following values:
|
expectsAcceptanceOf.name | Text | Name of the offer type, e.g. "High Definition", "Monthly subscription". |
expectsAcceptanceOf.price | Numeric | Cost of the offer type. Do not include a currency symbol. |
expectsAcceptanceOf.priceCurrency | Text | 3-letter currency code of the price value in ISO 4217 format, e.g. "USD". |
seller | Organization | Annotation for the company making the offer. Relevant only for offers where expectsAcceptanceOf.category isexternalSubscription, i.e. the user requires a subscription to an entity other than the watch action partner. Example: HBO GO content requires a cable subscription. |
seller.name | Text | The name of the external entity. |
seller.sameAs | URL | URL to the official homepage of the external entity. Example: IMDB, Wikipedia. |
The following examples demonstrate common use cases for the
expectsAcceptanceOf property."expectsAcceptanceOf": {
Compound conditions
Conditions can be combined in a single expectsAcceptanceOf block.
Sample expectsAcceptanceOf block for a deep link that is available on different cable providers for different dates:
"expectsAcceptanceOf": [
Sample markup
An example of a full markup block for a single movie.
<script type="application/ld+json">
Handling deep link intent in your Android app
Your application's
AndroidManifest.xml file must contain an intent filter with the following properties:- Accepts android.intent.action.VIEW
- Accepts android.intent.category.BROWSABLE
- Defines "android:scheme" in the <data> element
Here is an example intent filter:
<intent-filter>
You can read more about implementing this intent in the Android developer documentation.
Deep links should follow the standard URI format. You can read more about the URI here. Example:
android-app://com.cbs.app/cbs/shows/bbt/vid/2356865/occupation_recal?campaign=google_kp_watch
You can test your deep links with the deep link tester.
Subscribe to:
Posts (Atom)