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",
       ...
     },
   ...
   },
   ...
}

The following pseudocode represents the desired behavior when a user initiates playback:

if your app is installed
  open app and initiate playback
elseif your website supports playback
  open your website and initiate playback
else
  take user to your app's install page on the Play or App store and then
  initiate playback after your app is installed

To achieve the desired playback behavior, adhere to the following platform-specific requirements:

iOS
You must use Universal Links.
Android and Android TV
You can use either Android App Links or custom scheme links.

On Android and Android TV, you can also use custom scheme links. Your app's package_id must be included in the custom scheme URI. This ensures that the user is taken to your app's page on the Play Store if your app isn't installed. Therefore, the following URI formats are the only acceptable custom scheme formats for Media Actions:

android-app://{package_id}/{scheme}/{path}

For example:

android-app://com.partner.mynetworkapp/mynetwork/play?series=20114&title=21141&media=e90c89fa4

For more details, see the full specification.

intent://{package_id}/{scheme}/{path}

For example:

intent://com.partner.mynetworkapp/mynetwork/play?series=20114&title=21141&media=e90c89fa4

Other URI formats, like the example that follows, aren't acceptable custom scheme links for Media Actions:

scheme://{path}

For example:

mynetwork://play?series=20114&title=21141&media=e90c89fa4

Best practices

In the case that your app isn't installed and you don't have a web player, configure your web server to automatically redirect the user to either the Android or App store to install your app. To redirect, use Firebase dynamic links or third-party smart link platforms.

In the case that your app isn't installed and you do have a web player, provide a link or smart banner to either the Android or App store for users to install your app. The following is an example of an implemented smart banner:

An example of an implemented smart banner

The following table shows requirements and limitations for deep links, as they pertain to iOS, Android, and AndroidTV:

iOS Android and AndroidTV
http:// or https:// Required Recommended if the mobile website supports playback.
android-app:// or intent:// N/A Recommended if the mobile website doesn't support playback.
foo:// (arbitrary string) Not allowed Not allowed

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:

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.org/AndroidTVPlatform",
        "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.