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.
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
- Landing pages with the following schema.org markup
- MusicGroup
- MusicAlbum
- ListenAction
- First click free and autoplay functionality
- 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
- MusicGroup - a musical group or solo musician
- MusicAlbum - a collection of music tracks
- ListenAction - a link that begins playing media content
For example, iHeart could mark up auto-play links like this:
<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>
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: |
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 | 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.eligibleRegion(Required) | Country | If unspecified, we expect the Music Action is available everywhere except where denoted in potentialAction.. |
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. is specified. |
expectsAcceptanceOf.ineligibleRegion.name | Text | The 2-letter ISO 3166-1 alpha-2 country code. |
expectsAcceptanceOf.category | Enum | One of the following:
|
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.
<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.
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.
