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.

All deep links: Movie, TVEpisode, TVSeries, and TVSeason

  • Sign-in or purchase behavior: If your service requires a sign-in or purchase, the movie or episode must play, as appropriate for its type, afterwards. For more details, see the deep link guidelines that follow.

  • Playback: If your service tracks a user's state, playback must start from the user's previous marker on the movie or episode. Otherwise, playback must start from the beginning of the content.

TVSeries and TVSeason deep links only

  • Target episode selection: You must select the right target episode. If your service tracks a user's state, the target episode must be the episode that the user last stopped watching. Or, if the user completely finished the episode they were last watching, make the target episode the subsequent episode instead. Otherwise, the target episode must be one of the following at your discretion:

    • TVSeries
      • The first episode of the series. Recommended for serialized shows.
      • The first episode of the latest season. Recommended for long-running serialized shows.
      • The latest episode. Recommended for daily or news-related shows.
    • TVSeason
      • The first episode of the season. Recommended for serialized shows.
      • The latest episode. Recommended for daily or news-related shows.

    A deep link for TVSeries or TVSeason must be static (non-changing) and resolve to the target episode. Don't use the deep link for a specific episode.

    The following table provides several examples that demonstrate the required target episode selection logic for the TVSeries, TVSeason, and TVEpisode entity types:

    Target episode if the user last watched S6E24 Target episode if the user hasn't watched any episodes
    Series deep link
    • S6E24 (if the user hasn't finished S6E24)
    • S6E25 (if the user has finished watching S6E24)

    One of the following:

    • First episode of the series
    • First episode of the latest season
    • Latest episode
    Season deep link (S1-S5)
    • Whichever episode the user last watched in that season, or the first episode of the season if the user hasn't watched any episodes in that season.
    • First episode of the season
    Season deep link (S6)
    • S6E24 (if the user hasn't finished S6E24)
    • S6E25 (if the user has finished watching S6E24)

    One of the following:

    • First episode of the season
    • Latest episode
    Episode deep link
    • The specific episode that was clicked.
    • The specific episode that was clicked.

  • Autoplay: After you select a target episode, the required behavior depends on whether your service tracks a user's state.

    • If the user's state is tracked, do one of the following at your discretion:
      • Autoplay the episode immediately.
      • Prominently display the episode and make it playable within one click.
    • If the user's state isn't tracked, prominently display the episode and make it playable within one click.

Movie and TVEpisode deep links only

  • Autoplay: Movie and TVEpisode links must autoplay on all platforms.

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
Collect the Metadata
Next
Identify the Access Requirement