Ratings allow users to provide feedback about the tracks they like or dislike within your programmed radio or on demand music service. SMAPI supports multiple types of ratings; the specifics are defined by your service configuration. Most rating options are boolean states of individual icons (represented by rating values 0 and 1). However, multiple icons can be used together to form a set of related rating states (such as a thumbs up/thumbs down pair or a set of stars that collectively determine a numerical rating).
How ratings affect the music playing experience is up to your service, but there is an expectation that smart radio stations will give preference of some sort to tracks that users rate positively and avoid or lower the frequency of tracks that they rate down in some fashion. In addition, your service may choose to immediately skip to the next track when a user gives the current track a negative rating.
The rating could be any form; for example: starred or unstarred, or thumbs up or thumbs down, on a track. When implemented, the rating icon(s) are displayed on the Now Playing view as selectable button(s) that enable listeners rate items.
You should provide the same interface on Sonos that you do for your service. For example, if your native app features a two-button, thumbs-up, thumbs-down style rating interface, then you should provide the same interface for users on Sonos controllers. See the sample in Configure ratings for an example of this two-button interface.
The following items are essential for implementing dynamic ratings:
- Presentation map XML file: The presentation map includes the rating state as well as all available ratings.
- Strings XML file: Used for localization.
getExtendedMetadata: The Sonos Controller makes a getExtendedMetadata or getMediaMetadata request to learn the rating state.rateItem: When the listener selects a rating, the Controller makes a rateItem request with the track ID and rating value from the getExtendedMetadata or getMediaMetadata response.getLastUpdate: After a listener chooses a rating, the Controller issues a getLastUpdate request to update thefavoritesvalue.
This tutorial walks you through setting these items up in both a single and double icon scenario.
Workflow diagrams
The diagrams below show common ratings workflows.
Displaying the proper icon on the Now Playing screen
Changing the rating of a track
Displaying the updated state of a rated track
