Plan & Build
Dev Portal

Develop ratings

Get extended metadata

The Sonos app will make getExtendedMetadata or getMediaMetadata requests to learn about the rating icon state. Your implementation of getExtendedMetadata and getMediaMetadata should return a dynamic tag as part of the mediaMetadata. Inside the dynamic tag you may set any number of property tags, each of which should contain a name and a value.

When a track starts playing, the Sonos app looks at the property name and value defined in the property tag of mediaMetadata. It finds a match based on the Action and On Action Set Value fields on the Content Actions page of your Integration Submission Form. Then it displays the appropriate state for the rating icon or icons on the Now Playing view.

Here's a snippet from a sample getExtendedMetadata response with the dynamic tag:

<ns1:mediaMetadata>
  <ns1:id>TRACK:9c13647f-e5ce-4b0f-9f96</ns1:id>
  ...............
  <ns1:trackMetadata>
    <ns1:artistid>ARTIST:09ade3bd-b110-4277-b923</ns1:artistid>
    .......................
  </ns1:trackMetadata>
  <ns1:dynamic>
    <ns1:property>
      <ns1:name>add-favorite</ns1:name>
      <ns1:value>1</ns1:value>
    </ns1:property>
  </ns1:dynamic>
</ns1:mediaMetadata>

Rate item

At this point, you should be seeing rating icon or icons on the Now Playing view of the Sonos app. If the icon or icons do not appear, restart the app to force it to reload the Now Playing view based on the updated Content Action page.

When a listener selects a rating icon on the Now Playing view, the app makes a rateItem request to your SMAPI service. In this request, the id is the unique track or programmed radio identifier and rating is the On Action Set Value from the Action Input section.

Your SMAPI service should respond to this request by a rateItemResponse, with two optional values, shouldSkip and messageStringId. See rateItem for details.

rateItem sample request

<s:envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
 <s:body>
  <rateItem xmlns="http://www.sonos.com/Services/1.1">
   <id>TRACK0001</id>
   <rating>1</rating>
  </rateItem>
 </s:body>
</s:envelope>

rateItem sample response

<soap-env:envelope
    xmlns:ns1="http://www.sonos.com/Services/1.1"
    xmlns:soap-env="http://schemas.xmlsoap.org/soap/envelope/">
 <soap-env:body>
  <ns1:rateItemResponse>
   <ns1:rateItemResult>
    <ns1:shouldSkip>false</ns1:shouldSkip>
   </ns1:rateItemResult>
  </ns1:rateItemResponse>
 </soap-env:body>
</soap-env:envelope>

Get last update

Immediately after a user clicks one of the rating icons, the Sonos app issues a getLastUpdate request. This is to ensure that the app updates the favorites value, as, by choosing the ratings icon, the user has invalidated their personalized content.

When the app sees this favorites value change, it makes an additional getExtendedMetadata call and fetches the updated property value. Your SMAPI service should note the change in user rating content and reflect it in all subsequent requests. See getLastUpdate for details.

Dynamic ratings

In order to display rating information in the Sonos apps, your implementation of getExtendedMetadata and getMediaMetadata should return a dynamic tag as part of the mediaMetadata. This tag is used in coordination with the Content Actions page to display dynamic values on the Now Playing screen.

Content actions can be used for many ratings paradigms such as favoriting, un-favoriting, thumbs up, or thumbs down ratings on both tracks and streams. Additionally this mechanism adds the flexibility to be able to show and update any other dynamic data that you wish to associate with a track or stream.

Inside the dynamic tag you may set any number of property tags. Each property tag should contain a name and a value.

In order for the icons to update the favorites timestamp on getLastUpdate must change. When the Sonos app sees this value change it will make an additional getExtendedMetadata call to get the new rating value.

<ns1:mediaMetadata>
  <ns1:id>TRACK:9c13647f-e5ce-4b0f-9f96</ns1:id>
  ...............
  <ns1:trackMetadata>
    <ns1:artistid>ARTIST:09ade3bd-b110-4277-b923</ns1:artistid>
    .......................
  </ns1:trackMetadata>
  <ns1:dynamic>
    <ns1:property>
      <ns1:name>add-favorite</ns1:name>
      <ns1:value>1</ns1:value>
    </ns1:property>
  </ns1:dynamic>
</ns1:mediaMetadata>

Sonos apps use the Content Actions page to display this information on the Now Playing screen. The Content Actions page should define an Action Input with the Action Input Name and On Action Set Value. When a track is playing the Sonos app will look at the property defined in the dynamic tag of the mediaMetadata and find the match based on the Action Input Name and On Action Set Value, and display the appropriate ratings.

For more information about Action Inputs, see the Configure ratings page.

Updated 8 months ago