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.

## Deep link

The following are the requirements for the deep links:

- `urlTemplate` (of a [target object](https://developers.google.com/actions/media/reference/#target)) 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](https://developers.google.com/actions/media/collect-information/identify-the-deep-links#playback_behavior) 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",
           ...
         },
       ...
       },
       ...
    }

### Use deep links to initiate playback

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](https://developer.apple.com/ios/universal-links/).

Android and Android TV
:   You can use either [Android App Links](https://developer.android.com/training/app-links/index.html)
    or [custom scheme links](https://developers.google.com/actions/media/collect-information/identify-the-deep-links#custom-scheme-links).

> [!NOTE]
> **Objective:** Both iOS Universal Links and Android App Links can be configured to take the user to your app if it's installed, and to your website if your app isn't installed. If your service doesn't have a web-based player, configure your web server to automatically redirect the user to the appropriate store to install your app.

#### Custom scheme links for Android and Android TV

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](https://developer.android.com/reference/android/content/Intent#URI_ANDROID_APP_SCHEME).

`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](https://firebase.google.com/docs/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](https://developers.google.com/static/actions/media/images/implimentented-smart-link.png)

#### Summary of deep link requirements and limitations

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 across the multiple Google surfaces
that support Media Actions, comply with the following requirements:

- All partner supported platforms require a deep link for your content.
- For Chromecast platforms, you need to build a receiver using the latest [Cast Application Framework (CAF) Receiver SDK](https://developers.google.com/cast/docs/caf_receiver_overview).
- For mobile platforms (Android and iOS), see the requirememts in the [Use deep links to initiate playback](https://developers.google.com/actions/media/collect-information/identify-the-deep-links#universal-link) section.

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.

- **Autoplay:** Depending on the platform, it is required that your service prominently play the content after the target episode or movie is selected by the user.

  - **Search:** Autoplay is highly recommended, but is not required. If autoplay is not supported, the content must play within one click after the user is taken to your app or service.
  - **Android TV:** Autoplay is required for movie and episode.

#### 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. |

### Listen Actions playback behavior

For Listen Actions, we require the following playback behavior:

- Content must play within one click after the user is taken to your app or service.
- If your app or platform requires a sign-in, it needs to play the content immediately or within one click after the sign-in.
- Your app or platform must offer at least one way for all users to play the exact song, album, artist, or playlist.
  - For users ineligible to play the exact content (for example, they don't have the required subscription), your service must explain what the user needs to do to become eligible to play the exact content upon arriving at your app or platform.

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.

## Identify the deep links

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`](https://developers.google.com/actions/media/reference/data-specification/watch-actions-common-specification#action_markup_properties) property for that deep link. See the [additionalProperty](https://developers.google.com/actions/media/reference/feed-examples/watch-actions-examples#additionalproperty) example.