Pages

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.
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.
The following properties should be defined for every Movie and TVEpisode item.
PropertyTypeDescription
@id (Recommended)TextGlobally unique ID of the Movie or TVEpisode. The ID should be stable and not change over time.
name (Required)TextName of the Movie or TVEpisode.
urlURLURL to partner's landing page for the Movie or TVEpisode.
descriptionTextA synopsis of the work. Plot synopses are preferred to factual summaries.
releasedEvent(Recommended)PublicationEventAnnotation for the original release date.
releasedEvent.startDate(Recommended)DateOriginal broadcast/theatrical release date of the work, in ISO 8601 format.
releasedEvent.locationCountryAnnotation for the country of original release.
releasedEvent.location.nameTextCountry in which the work was released on the above startDate. Use the 2-letter ISO 3166 country code.
potentialAction(Required)WatchActionAnnotation(s) for the full-length Movie or TVEpisode. See the "Markup for deep links" section below for details.
hasPartTVClip or ClipAnnotation(s) for short videos related to the Movie (use Clip) or TVEpisode (use TVClip).
hasPart.descriptionTextOne of the following values:
  • "trailer": A preview or advertisement of the work.
  • "behind_the_scenes": A summary of the production of the work.
  • "highlight": A contiguous scene from the work.
hasPart.timeRequiredTextDuration of the clip in ISO 8601 format, e.g. "PT2M5S" (2min 5sec).
hasPart.potentialActionWatchActionAnnotation(s) for the clip. See the "Markup for deep links" section below for details.
imageImageObjectAnnotation(s) for images related to the work. Provide highest-resolution available. PNG and JPG preferred.
image.heightIntegerHeight of the image in pixels.
image.widthIntegerWidth of the image in pixels.
image.urlURLURL where the image can be fetched.
sameAsURLURL to a reference web page that unambiguously identifies the work. Example: IMDB, Wikipedia.
actorPersonAnnotation(s) for each cast member.
actor.nameTextActor name.
actor.sameAsURLURL to a reference web page that unambiguously identifies the actor. Example: IMDB, Wikipedia.
directorPersonAnnotation(s) of the director.
director.nameTextDirector name.
director.sameAsURLURL 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.
PropertyTypeDescription
@id (Recommended)TextGlobally unique ID of the TVSeason. The ID should be stable and not change over time.
nameTextName of the TVSeason, if it differs from the series name.
sameAsURLURL to a reference web page that unambiguously identifies the season. Example: IMDB, Wikipedia.
url (Recommended)URLURL to partner's season landing page.
potentialAction(Recommended)ViewActionAnnotation(s) for the season. See the "Markup for deep links" section below for details.
releasedEvent(Recommended)PublicationEventAnnotation for the original release date of the first episode of the season.
releasedEvent.startDate(Recommended)DateOriginal broadcast date of the first episode of the season, in ISO 8601 format.
releasedEvent.locationCountryAnnotation for the country of original release.
releasedEvent.location.nameTextCountry in which the season premiered on the above startDate. Use the 2-letter ISO 3166 country code.
seasonNumber (Required)IntegerPosition of the season within an ordered group of seasons.
partOfSeries (Required)TVSeriesAnnotation for the series of the season.
partOfSeries.name (Required)TextName of the TV series.
partOfSeries.sameAsURLURL to a reference web page that unambiguously identifies the series. Example: IMDB, Wikipedia.
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.
PropertyTypeDescription
target (Required)URLDeep link(s) to content. Examples:
  • Desktop: "http://www.example.com/big_bang_theory/s7/e13?autoplay=true"
  • Android: "android-app://com.app.foo/bar/big_bang_theory/s7/e13?autoplay=true"
  • iOS: "ios-app://530168168/bar/big_bang_theory/s7/e13?autoplay=true"
expectsAcceptanceOf (Required)OfferAnnotation(s) for the conditions of the deeplink.
expectsAcceptanceOf.availabilityStarts(Required)DateDate after which the watch action is available, in ISO 8601 format.
expectsAcceptanceOf.availabilityEnds(Required)DateDate after which the watch action is no longer available, in ISO 8601 format.
expectsAcceptanceOf.eligibleRegion(Recommended)CountryCountries in which the watch action is available. If unspecified, we expect the action is available everywhere except where denoted in potentialAction.expectsAcceptanceOf.ineligibleRegion.
expectsAcceptanceOf.eligibleRegion.name(Recommended)TextCountry name. Use the ISO 3166 country code.
expectsAcceptanceOf.ineligibleRegionCountryCountries in which the watch action is not available. If unspecified, we expect the action is available everywhere unless potentialAction.expectsAcceptanceOf.eligibleRegion is specified.
expectsAcceptanceOf.ineligibleRegion.nameTextCountry name. Use the ISO 3166 country code.
expectsAcceptanceOf.category (Required)TextOne of the following values:
  • "rental": The watch action is available to the user after purchase for a finite amount of time.
  • "purchase": The watch action is available to the user after purchase for an indefinite amount of time.
  • "subscription": The watch action is included with a subscription to the partner itself.
  • "externalSubscription": The watch action is included with a subscription to an external entity, e.g. cable provider.
  • "free": The watch action is available with no purchase or subscription required of the user. The watch action may require a user login or contain ads.
expectsAcceptanceOf.nameTextName of the offer type, e.g. "High Definition", "Monthly subscription".
expectsAcceptanceOf.priceNumericCost of the offer type. Do not include a currency symbol.
expectsAcceptanceOf.priceCurrencyText3-letter currency code of the price value in ISO 4217 format, e.g. "USD".
sellerOrganizationAnnotation 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.nameTextThe name of the external entity.
seller.sameAsURLURL to the official homepage of the external entity. Example: IMDB, Wikipedia.
The following examples demonstrate common use cases for the expectsAcceptanceOf property.
"expectsAcceptanceOf": {
  "@type": "Offer",
  "availabilityStarts": "2014-10-01T00:00",
  "availabilityEnds": "2014-12-31T00:00"
}

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": [
  {
    "@type": "Offer",
    "availabilityStarts": "2014-10-01T00:00",
    "availabilityEnds": "2014-12-31T00:00",
    "category": "externalSubscription",
    "seller": {
      "@type": "Organization",
      "name": "Comcast",
      "sameAs": "http://www.comcast.com/"
    }
  },
  {
    "@type": "Offer",
    "availabilityStarts": "2015-01-01T00:00",
    "availabilityEnds": "2015-03-31T00:00",
    "category": "externalSubscription",
    "seller": {
      "@type": "Organization",
      "name": "Time Warner Cable",
      "sameAs": "http://www.timewarnercable.com/"
    }
  }
]

Sample markup

An example of a full markup block for a single movie.
<script type="application/ld+json">
{
  "@context":"http://schema.org",
  "@id":"12546432",
  "@type":"Movie",
  "name":"Forrest Gump",
  "url":"http://www.example.com/forrest_gump",
  "description":"A man with a low I.Q. has accomplished great things in his life and been present during significant historic events.",
  "releasedEvent":{
    "@type":"PublicationEvent",
    "startDate":"1994-07-06",
    "location":{
      "@type":"Country",
      "name":"US"
    }
  },
  "potentialAction":{
    "@type":"WatchAction",
    "target":[
      "http://www.example.com/forrest_gump?autoplay=true",
      "android-app://com.app.foo/bar/forrest_gump?autoplay=true"
    ],
    "expectsAcceptanceOf":{
      "@type":"Offer",
      "availabilityStarts":"2015-01-01T00:00",
      "availabilityStarts":"2015-12-31T00:00",
      "category":"subscription",
      "name":"Hulu Plus",
      "price":7.99,
      "priceCurrency":"USD",
      "seller":{
        "@type":"Organization",
        "name":"Hulu",
        "sameAs":"http://www.hulu.com/"
      }
    }
  },
  "hasPart":{
    "@type":"Clip",
    "description":"trailer",
    "timeRequired":"PT2M5S",
    "potentialAction":{
      "@type":"WatchAction",
      "target":"android-app://com.app.foo/bar/watch/2356866",
      "expectsAcceptanceOf":{
        "category":"free",
        "availabilityStarts":"2014-09-01T00:00",
        "availabilityEnds":"2015-09-01T00:00"
      }
    }
  },
  "image":{
    "@type":"ImageObject",
    "height":600,
    "width":400,
    "url":"http://www.hulu.com/images/124564.jpg"
  },
  "sameAs":"http://www.imdb.com/title/tt0109830/",
  "actor":{
    "@type":"Person",
    "name":"Tom Hanks",
    "sameAs":"http://www.imdb.com/name/nm0000158/"
  },
  "director":{
    "@type":"Person",
    "name":"Robert Zemeckis",
    "sameAs":"http://www.imdb.com/name/nm0000709/"
  },
  "duration":"PT2H22M"
}
</script>
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>
  <action android:name="android.intent.action.VIEW"/>
  <category android:name="android.intent.category.DEFAULT"/>
  <category android:name="android.intent.category.BROWSABLE"/>
  <data android:scheme="cbs"/>
</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.