Identify the platform-specific deep links of your content

When a user initiates Media Actions on content (for example, a user clicks on your icon on Google Search), Google takes the user directly to the content in your app or platform using the content's deep link.

The following are the requirements for the deep links:

  • urlTemplate (of a target object) requires a deep link.
  • Deep links need to open the content they target on all platforms specified.
  • Deep links can include parameters (&) or anchor tags (#).
    • If autoplay is not activated by default, we recommend you append a parameter, such as &autoplay=true, to the deep link to activate the autoplay feature on your app or platform.

Example of @id, url, and urlTemplate:

{
   "@context": ["http://schema.org", {"@language": "en"}],
   "@type": "Movie",
   "@id": "http://www.example.com/my_favorite_movie",
   "url": "http://www.example.com/my_favorite_movie",
   "name": "My Favorite Movie",
   "potentialAction": {
     "@type": "WatchAction",
     "target": {
       "@type": "EntryPoint",
       "urlTemplate": "http://www.example.com/my_favorite_movie&autoplay=true",
       ...
     },
   ...
   },
   ...
}

Some device-specific platforms support universal links (for example, Apple's Universal Link and Android's App Link). Without visiting a web page or opening a web browser, universal links, which are HTTP URLs, can take users directly to your app on their devices. The following are the requirements for the universal links:

  • For iOS and Chromecast, we require you support universal links.
  • For Android, we recommend you support universal links.
    • If you don't support the universal link format, use the following URL format: android-app://{package_id}/{scheme}/{path}
      • For example, abcnetwork://play?series=20114&title=21141&media=e90c89fa4 needs to be represented as android-app://com.partner.abcnetworkapp/abcnetwork/play?series=20114&title=21141&media=e90c89fa4

To learn how to implement universal links, see iOS Documentation and Android Documentation.

Platform types

To ensure that your content is available on Google's multiple platforms (Search, Assistant, Android TV, and Chromecast), comply with the following requirements:

  • All supported platforms require a deep link from your content.
  • For Chromecast platforms, you need to build a receiver using the latest Cast Application Framework (CAF) Receiver SDK.
  • On mobile platforms (Android and iOS), if a user initiates Media Actions, but your app isn't installed on the user's device, one of the following must happen:
    • The user is directed to the App Store or Play Store and is prompted to install the app.
    • The user is directed to a web page and is prompted to download the app in one click.

The following table contains a list of the platforms that support Media Actions:

Platform Description
http://schema.org/DesktopWebPlatform Search platform on desktop web browser.
http://schema.org/MobileWebPlatform Search platform on mobile web browser.
http://schema.org/AndroidPlatform Search and PlayGuide platforms on Android app.
http://schema.org/AndroidTVPlatform Android TV platform on Android TV app.
http://schema.org/IOSPlatform Search platform on iOS app.
http://schema.googleapis.com/GoogleVideoCast Cast and Home platforms on a Chromecast device.
http://schema.googleapis.com/GoogleAudioCast Listen Actions only. Cast and Home platforms on a Chromecast device.

Example of an entity with two different deep links:

"potentialAction": {
  "@type": "WatchAction",
  "target": [
    {
      "@type": "EntryPoint",
      "urlTemplate": "http://www.example.com/standardView",
      "actionPlatform": [
        "http://schema.org/DesktopWebPlatform",
        "http://schema.org/MobileWebPlatform"
      ]
    },
    {
      "@type":"EntryPoint",
      "urlTemplate":"http://example.com/multipleViews",
      "actionPlatform": [
        "http://schema.org/IOSPlatform",
        "http://schema.org/AndroidPlatform",
        "http://schema.googleapis.com/GoogleVideoCast"
      ],
      "additionalProperty": [
        {
          "@type": "PropertyValue",
          "name": "videoFormat",
          "value": [ "HD", "4K" ]
        }
      ],
    }
  ],
  ...
}

Playback behavior

For most content, when Google takes users to your app or platform, we require you to autoplay the selected content. This allows users to quickly start watching or listening to the content.

Watch Actions playback behavior

For Watch Actions, we require the following playback behavior:

  • For Movie and TVEpisode, content must autoplay on all platforms.
    • If your app or platform tracks a user’s state, playback needs to start from the user’s previous marker on the content.
    • If your app or platform doesn’t track a user’s state, or if a user watches the content for the first time, playback needs to start from the beginning of the content.
  • For TVSeries and TVSeason, content must autoplay on Chromecast and Android TV.
    • On other platforms, playback needs to be within one click (however, we recommend autoplay).
    • Your app or platform needs to autoplay the earliest episode available in the series or season.
      • However, if the TV show is currently airing, provide a deep link that will always resolve to the most recent episode.
      • A deep link for TVSeries or TVSeason needs to be static (that is, non-changing) and resolve to the appropriate episode; do not use the deep link for a specific episode.
    • If your app or platform tracks a user’s state, playback needs to start from the user’s previous marker on the episode that the user last watched in the series or season.
  • If your app or platform requires a sign-in, it needs to play the content immediately after the sign-in.

Listen Actions playback behavior

For Listen Actions, we require the following playback behavior:

  • Content must autoplay on all platforms.
    • However, on iOS, playback can be within one click.
  • If your app or platform requires a sign-in, it needs to play the content immediately after the sign-in.

We recommend the following best practices for your app or platform:

  • For MusicGroup, play different content from the artist each time a user selects the artist.
  • For MusicAlbum, play content in the order of appearance in the album.
  • For MusicPlaylist, play different content from the playlist each time a user selects the playlist.

Do the following:

  1. For each content, check if it has different deep links based on the platforms.
  2. For each deep link, ask the following questions about its entry point (the page on your app or platform the deep link takes you to):
    • Does the entry point (not the content) support multiple languages?
    • Does the entry point support multiple subtitle languages?
    • Does the entry point support multiple camera angles?
    • Does the entry point support multiple video formats?

If your answer is yes to any of these questions, you need to provide the additionalProperty property for that deep link. See the additionalProperty example.

Previous
Next