Once you’ve determined whether to use a one-button or two-button implementation and created your ratings artwork, you can set up your presentation map. Use the samples below as starting points and customize them for your implementation.

SMAPI uses a PresentationMap element as well as Match elements and the Rating sub-element to determine the rating icon to display for an item. Match elements are also used with MenuItemOverrides in Add actions, imageSizeMap in Add album art, browseIconSizeMap in Add browse icons, and SearchCategories in Add search.

The sections below describe the PresentationMap, Match, and Rating elements in detail.

Presentation Map

The presentation map for ratings must be the NowPlayingRatings type:

Set trackEnabled to true to enable ratings for on demand tracks. Set programEnabled to true to enable ratings for programmed radio. For example, to enable ratings for on demand only, set trackEnabled to true and programEnabled to false, as shown below.

See the Presentation Map Elements table for details.

Match element

The propname attribute in the Match element identifies the rating functionality. If you change the propname, be sure to use the same name for each Match element in your ratings implementation.

The value attribute in the Match element identifies the property value. All possible rating combinations should be assigned a unique property value, for example:

Sonos apps use the propname and value attributes of the Match element to set the rating for an item. The getExtendedMetadataResponse and getMetadataResponse responses return these values in the mediaMetadata element. See Develop ratings for details.

The Match tag determines the state of the rating. So, for example, you could have a one star rating that cycles through five different states, with different color icons, by adding five Match tags and the appropriate sub-elements.

Rating Element

The Rating element represents an icon along with its state. It includes Icon sub-elements with URLs to the images used on the Now Playing view of each app to show the rating.

Each Rating element has an Id attribute that must be an integer unique to the property name. The Sonos app sends this Id to your service when a user rates an item. See Develop ratings for details.

You must provide rating icons for every Sonos app listed in the Controller attribute section of the Presentation Map Elements table. Therefore, each Rating element must include one Icon sub-element per Controller. acr, acr-hdpi, icr, pcdcr, macdcr, and cr200 icons should be PNGs. The universal icon must be an SVG. Be sure to use the correct size icons for each icon as specified in the guidelines. See the Use rating icons for details about the required files and file formats.

If you change the icon or update it in any way, you must also update the LastModified attribute to force the Sonos app to re-load the image from its origin. Otherwise, the app will continue to use the image previously downloaded and stored in its local cache.

The order of the ratings in these match values matter. In a two button implementation, the Sonos app displays the first rating in the presentation map on the left side of the app. The app displays the next rating to the right. Be sure to use the same order for the icons in each match tag.

If you do not require details about which icon was pressed, you could simplify your implementation to only note whether the returned value of the Rating Id is even or odd, and act accordingly. In the example below, all thumbs up actions are odd, and all thumbs down actions are even.

No rating implementation

If you don’t want to offer ratings for your service, simply do not include a presentation map section with a NowPlayingRatings type.

One-button Rating implementation

We’ve configured the presentation map in this section for a one-button rating implementation with two states, starred or unstarred. To offer a one-button rating implementation, copy the presentation map below and customize it for your service.

Two-button Rating Implementation

We’ve configured the presentation map in this section for a two-button rating implementation with two icons each with two states, selected or unselected. To offer a two-button rating implementation, copy the presentation map below and customize it for your service.

Presentation Map Elements

The table below describes the elements and attributes for a Ratings presentation map. The PresentationMap tag should have the following attributes:

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.
programEnabled	Boolean	Set to true if ratings should be enabled for Programmed Radio.

An Icon has the following attributes:

Name	Type	Description
Controller	Enumeration	There must be one Icon tag for each of the following: acr — Android controllers. 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 date 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 to the location of the icon image. For all but the universal controller, the image must be in the PNG file format and should support transparency. The universal controller must be in the SVG file format. 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. See the Use rating icons for details.

A Rating has the following attributes:

Name	Type	Description
AutoSkip	Enumeration	This defines whether or not this track should be skipped when a listener clicks this rating icon. This is useful for a thumbs down or ban rating where the user has indicated that they don’t like the track. Must be one of the following values: ASK, ALWAYS or NEVER.
Id	int	This is the value that will be passed to the rateItem method. The Id must be unique for the given property name.
OnSuccessStringId	string(128)	This is the ID of the String that will be displayed if the rateItem call is successful after clicking the icon. If you add this attribute, it must correlate with a String Id in the Strings XML file. See Configure ratings for details.
State	Enumeration	The state of the rating. Must be one of the following values: DEFAULT, RATED, UNRATED. Currently, DEFAULT acts the same as UNRATED.
StringId	string(128)	This is the ID of the string that will be displayed on MouseOver of the Rating Icon. If you add this attribute, it must correlate with a String Id in the Strings XML file. See Configure ratings for details.
Type	Enumeration	The type of rating for the Sonos app to display. Must be one of the following: STAR, THUMBSUP, THUMBSDOWN, LOVE, HATE, BAN.

---

Strings

If you’re not familiar with Strings XML, read Strings and localization before you continue.

Continuing with the ratings implementation, we will now add two string messages, each with a stringId for every Rating tag:

1. stringId: displayed when mouse is hovered over the Rating icon;
2. OnSuccessStringId: when the call associated with the Rating icon (rateItem) is successful.

We will add the following to our Strings XML: