Develop ratings

Follow the instructions below to develop and enable 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 Match tags inside the presentation map XML file. Then it displays the appropriate state for the rating icon or icons on the Now Playing view.

Snippet from a sample getExtendedMetadataResponse with the dynamic tag:

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 re-map the Now Playing view based on the updated presentation map XML.

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 rating ID from the presentation map.

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

rateItem sample response

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 Presentation Map XML file to display dynamic values on the Now Playing screen.

This tag can be used for many ratings paradigms such as staring, unstaring, 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.

Sonos apps use the Presentation Map XML file to display this information on the Now Playing Screen. The Presentation Map XML file should define a Match tag with the attributes propname and 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 property name and value and display the appropriate ratings. See Configure ratings for details.

In the Presentation Map XML file you should define a Match of each property name and property value combination. For each Match you may define up to 2 ratings.

The PresentationMap tag should have the attributes in the table below.

Name Type Description
type String This must be set to NowPlayingRatings
trackEnabled Boolean Set to true if ratings should be enabled for tracks. Use this for On Demand music and Programmed Radio.
programEnabled Boolean Set to true if ratings should be enabled for Streaming Radio.

A Rating has the attributes in the table below

Name Type Description
Id int This is the value that will be passed to the rateItem method. The ID must be unique for the given property name.
StringId string(128) This is the ID of the string that will be displayed on MouseOver of the rating icon, which must correlate with a string ID in the Strings XML file.
AutoSkip Enumeration Must be one of the following: ASK, ALWAYS or NEVER. This defines whether or not this track should be skipped when this rating icon is clicked. This is useful for a Thumbs Down or Ban rating where the user has indicated not liking the track.
OnSuccessStringId string(128) This is the ID of the string that the app displays after a listener clicks the icon and the rateItem call is successful. This must correlate with a string ID in the Strings XML file.

In the Rating tag you must list icons for each Sonos app. An Icon has the following attributes:

Name Type Description
Controller Enumeration There must be one Icon tag for each of the following:

  • acr — Android apps.
  • acr-hdpi — Android tablets.
  • icr — iPhone and iPad.
  • pcdcr — Windows.
  • macdcr — Mac OSX.
  • cr200 — Sonos CR200 controller.
  • universal — hi-res ratings for Android and iOS.
LastModified Date This is a data string in the format 10:29:20 17 Aug 2011. This date must be updated any time the icons change even if the icon URL has changed as well.
Uri String The URI of the icon image. The image must be in the PNG file format and should support transparency. The 36×36 pixel icon should be used for the icr and acr Controller types; the 54×54 pixel icon should be used for the acr-hdpi; the 44×44 pixel icon should be used for the CR200 controller; the 21×21 pixel icon should be used for the desktop controllers.

The following is an example of how to configure starring and unstarring in the presentation map: