Music Play Actions

Music actions make Google Search an entry point for discovering and listening to music artists and their songs. Music actions can appear in Google properties such as Knowledge Panel, enabling users to listen to songs from streaming services.

We are currently piloting this feature with a restricted set of initial data providers. We hope to soon open up the feature so any provider who implements spec-compliant markup is eligible to participate.

When a user searches for the name of an artist on Google or on their mobile device, a Knowledge Panel "card" may appear prominently in the Search results. Music 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 artist.

Integrating music actions is straightforward:

Landing pages must contain appropriate schema.org markup. For a streamlined user experience, we recommend deep links support autoplay. When users click a Music Action link, partner content should immediately start playing -- instead of directing the user to a landing page where they must click again to start playback.

Integration requirements

1. Landing pages with the following schema.org markup
   1. MusicGroup
   2. MusicAlbum
   3. ListenAction
2. First click free and autoplay functionality
3. Google auth integration

Integration details

By integrating with Music Actions, a partner will qualify to surface "deep links" in Knowledge Graph results on Google Search that will begin auto-playing media content. A deep link is a URL that points to a specific music artist or album from the partner's inventory.

Schema.org markup

Music Actions enable a partner to surface "Listen" actions by making the Knowledge Graph aware of its available albums and artist radio stations. The minimum requirements for this integration are annotations of the partner's artist and album landing pages using the following industry standard schema.org markup

1. MusicGroup - a musical group or solo musician
2. MusicAlbum - a collection of music tracks
3. ListenAction - a link that begins playing media content

For example, iHeart could mark up auto-play links like this:

JSON-LDMICRODATA

<script type="application/ld+json">
{
  "@context": "http://schema.org",
  "@type": "MusicGroup",
  "url": [
    "http://www.iheart.com/artist/Katy-Perry-35141/",
    "android-app://com.clearchannel.iheartradio.controller/ihr/listen/custom_radio/artist/35141"
  ],
  "name": "Katy Perry",
  "sameAs": "http://www.katyperry.com",
  "description": "Katy Perry is a pop music artist.",
  "potentialAction": {
    "@type": "ListenAction",
    "target": [
      "http://www.iheart.com/artist/Katy-Perry-35141/?autoplay=true&ext=1&playedFrom=197",
      "android-app://com.clearchannel.iheartradio.controller/ihr/listen/custom_radio/artist/35141?ext=1&played_from=197"
    ]
  }
}
</script>

Note: Mark up your content using JSON-LD (preferred) or Microdata, but not both.

While we encourage partners to provide as much markup as they would like for MusicGroup and MusicAlbum, there is a minimum set of fields that should be provided. The following table lists the required and recommended fields.

Property	Type	Description
name (Required)	Text	Artist or album name.
description (Required)	Text	A biography of the artist or a description of the album.
url (Required)	URL	URL of the landing page of the artist or album on the partner site.
image	URL	URL of an image of the artist or album.
sameAs (Recommended)	URL	URL of a page that unambiguously identifies the artist or album. Example: Wikipedia.
potentialAction(Required)	ListenAction	Deeplink annotation(s).
potentialAction.target(Required)	ListenAction	Deeplink URI(s) to listen to the artist's/album's songs. Example: Desktop: http://www.foo.com/lady_gaga?autoplay=true Android: android-app://{apk_name}/{scheme}/{host_path}. See here for details. iOS: ios-app://{app_store_id}/{scheme}/{host_path}. Seehere for details.

Besides providing this information in markup, it is important that the information is visible to users on the page as well. The partner should also note that we will be using Googlebot to crawl their pages; it is okay for the schema.org markup to appear only to Googlebot.

Providing regional/time/paywall restrictions

The partner may have restrictions on which regions can listen to songs or when certain songs are available. Or access to the partner's inventory may be restricted to paying customers only. In such cases, the partner should provide details about the restrictions in the schema.org markup.

The following table lists the restrictions that partners can provide in their markup in each potentialAction.

Property	Type	Description
expectsAcceptanceOf (Required)	Offer	Annotation for the condition(s) that must be met for the Music Action to be available.
expectsAcceptanceOf.availabilityStarts	Date	Date after which the Music Action is available, in ISO 8601 format. If unspecified, we expect the action is available anytime prior topotentialAction.expectsAcceptanceOf.availabilityEnds.
expectsAcceptanceOf.availabilityEnds	Date	Date after which the Music Action is no longer available, in ISO 8601 format. If unspecified, we expect the action is available indefinitely after potentialAction.expectsAcceptanceOf.availabilityStarts.
expectsAcceptanceOf.eligibleRegion(Required)	Country	If unspecified, we expect the Music Action is available everywhere except where denoted in potentialAction.expectsAcceptanceOf.ineligibleRegion.
expectsAcceptanceOf.eligibleRegion.name(Required)	Text	The 2-letter ISO 3166-1 alpha-2 country code.
expectsAcceptanceOf.ineligibleRegion	Country	If unspecified, we expect the Music Action is available everywhere unless potentialAction.expectsAcceptanceOf.eligibleRegion is specified.
expectsAcceptanceOf.ineligibleRegion.name	Text	The 2-letter ISO 3166-1 alpha-2 country code.
expectsAcceptanceOf.category	Enum	One of the following: "purchase": The Music Action is available to the user after purchase for an indefinite amount of time. "subscription": The Music Action is included with a subscription to the partner itself. "free": The Music Action is available with no purchase or subscription required of the user. The Music Action may require a user login or contain ads. This value defaults to "free".
expectsAcceptanceOf.name	Text	Name of the offer type.
expectsAcceptanceOf.price	Numeric	Cost of the offer type.
expectsAcceptanceOf.priceCurrency	Text	The 3-letter ISO 4217 currency code of the price value.

The following are sample markup for various restriction cases.

US ONLYNOT AVAILABLE IN CHINAUS AND CANADA, BY SUBSCRIPTIONUS FIRST, LATER IN CANADA

<script type="application/ld+json">
{
  "@context": "http://schema.org",
  "@type": "MusicAlbum",
  "name": "Example Album",
  "description": "A group of great songs.",
  "url": "https://www.example.com/listen",
  "image": "http://www.example.com/image",
  "potentialAction": {
    "@type": "ListenAction",
    "target": "https://www.example.com/listen",
    "expectsAcceptanceOf": {
      "@type": "Offer",
      "eligibleRegion": {
        "@type": "Country",
        "name": "US"
      }
    }
  }
}
</script>

Testing markup

Partners should test their markup by using the Structured Data Testing Tool. You can either provide a single URL or paste HTML to see how Google interprets your markup.

Important: As mentioned above, we will be using Googlebot to do the crawling. If your page only shows markup to Googlebot, providing a URL for this tool will not work as the tool uses a different bot. Instead, you should paste HTML to test your markup.

There are a few things to look for while using this tool:

• Make sure that the top-level and first schema.org entity corresponds with the page's main content. For example, if the page is for Bruno Mars, the first and top-most entity should be MusicGroup. If it's for a Katy Perry album, the first and top-most entity should be MusicAlbum.
• There will be a warning message about potentialAction. It is okay to ignore that message for now. However, make sure that potentialAction hangs off of the right entity and the "target" URLs are correctly specified.

Handling deep link intent in your Android app

The intent-filter that you use to handle requests from Google should use the VIEW action. After launching the deeplink, the app should automatically start playing music. A common way to use the same deeplink for both Music Play Actions and app indexing is to use a URL parameter to signal autoplay, e.g. &autoplay=true.

The "content" in the markup above that begins with "android-app://" provides Google with deep links into your app for specific artists or albums. The format of the "android-app://" URI is as follows:

android-app://<package name of your app>/<android:scheme>/<rest of the deep link>

Google will translate this annotation to the following deep link to use to open your app:

<android:scheme>://<rest of the deep link>

So for the Katy Perry example above, the following:

android-app://com.clearchannel.iheartradio.controller/ihr/listen/custom_radio/artist/35141?ext=1&played_from=197

would indicate to Google that the app can be opened to play Katy Perry with the following deep link:

ihr://listen/custom_radio/artist/35141?ext=1&played_from=197

You need to also specify the <data> element in your intent-filter. For the example above, the intent-filter would be specified as follows in your app's manifest file:

<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="ihr"/> </intent-filter>

You can test that your app properly handles the deep links by using the following ADB command:

adb shell am start "[deep link]"

Further, you can test it by creating an HTML page that has the following links:

intent://listen/custom_radio/artist/35141?ext=1&played_from=197#Intent;scheme=ihr;package=com.clearchannel.iheartradio.controller;action=android.intent.action.VIEW;end

This will open the iHeart app with the VIEW action on this deep link:

ihr://listen/custom_radio/artist/35141?ext=1&played_from=197

You can learn more about these "intent" links here.