Use a presentation map file to customize how the Sonos app displays your service. A presentation map file is an XML configuration file that enables you to customize certain presentation and functional aspects of your music service in Sonos firmware. Host this file publicly and enter its URL in the “Technical Configuration” section on the version set up form on Sonos Labs. When published, Sonos apps download the file from this URL when a customer adds your service to their household. Note that this URL should not exceed 64-characters.

The presentation map allows configuration of:

Unified Search
Hi-Res Custom Browse Icons
Hi-Res Album Art
SMAPI Ratings
Menu Item Overrides
Browse Options

Presentation maps are objects that exist inside a presentation map XML file. The file consists of a version 1.0 XML file with UTF-8 encoding and a <Presentation> element. For example:

<?xml version='1.0' encoding='UTF-8'?>
<Presentation>
    <PresentationMap type="Search">
    ...
    </PresentationMap>
    <PresentationMap type="Ratings">
    ...
    </PresentationMap>
    <PresentationMap type="DisplayType">
    ...
    </PresentationMap>
</Presentation>

<?xml version='1.0' encoding='UTF-8'?>

...

</PresentationMap>

...

</PresentationMap>

...

</PresentationMap>

</Presentation>

Search

If your service supports the ability to search content, then you must configure search in a presentation map. See Add search for details.

Hi-Res Custom Browse Icons

If your service supports custom browse icons, you must configure this feature in your presentation map. You must implement two styles of icons, one for mobile and one for desktop Sonos apps, and configure a set of substitution rules to enable the Sonos app to select and display the correct icon depending on OS platform and app version. See Add browse icons for details.

Hi-Res Album Art

If your service delivers album art on the Now Playing screen for music that is playing, you must configure this feature in your presentation map. Configure a set of substitution rules to enable the Sonos app to select and display the correct album art depending on OS platform and app version. See Add album art for details.

SMAPI Ratings

If your service allows a listener to rate a track or stream, then you must configure this feature in your presentation map. This configuration sets up the ratings UX for the Now Playing screen in the Sonos app. The presentation map configuration includes definition of the icons used in the UX, what tags the Sonos app should look for when determining which icon to show, and what values will be submitted in rateItem when a listener taps a rating on the Now Playing screen. See Add ratings for details.

Info View Menu Overrides

If your service has implemented the ability to start up a radio stream related to the current item playing, you can override the default strings in the Sonos app that display in the Info View. For instance, the default string “Start Radio” can be changed to “Go To Radio” or something more appropriate for your service. See Related play for details.

Browse Options

Browse options allow you to override certain standard browse behaviors of Sonos apps. At the moment, the only browse option you can configure is the count attribute of getMetadata and search requests. By default, all getMetadata requests from Sonos apps ask for 100 items to be returned (the Sonos CR200 asks for 500). You can increase or decrease this value based on your preference:

<?xml version="1.0" encoding="utf-8" ?>
<Presentation>
    <!-- BrowseOptions allow for an override of standard
         browse operations in the Sonos app. The setting
         below will force the Sonos app to ask for 250
         items in each getMedata request. -->
    <BrowseOptions PageSize="250" />
</Presentation>

<?xml version="1.0" encoding="utf-8" ?>

<!-- BrowseOptions allow for an override of standard

browse operations in the Sonos app. The setting

below will force the Sonos app to ask for 250

items in each getMedata request. -->

</Presentation>

Customize items with display types

You can customize how Sonos Android and iOS Sonos apps display items such as albums, tracks, and playlists by using display types. Display types determine how Sonos apps display items such as albums, tracks, and playlists. You can use them to determine how Sonos apps display album art and lines of text for these items. Set up display types in your presentation map by specifying one of the following display modes:

Grid
List
Hero
Editorial

Set up display types using display modes

You can use the following display modes when setting up display types.

Grid

The GRID display mode displays items in a grid, with tile-sized album art displayed above a maximum of two lines of text. The Sonos app will show default album art if you don’t provide any.

List

The LIST display mode displays items in a list, with small album art and a maximum of two lines of text displayed to the right. Sonos apps will show default album art if you don’t provide any.

Hero

The HERO display mode shows a container, such as an album or playlist, with a header and a list of child elements within the container. The header includes an image and up to three lines of text. The child elements can contain a thumbnail and up to three lines of text, depending on the child element’s display type. On tablets, the header is listed on the left side of the screen, with the text below, and the child elements on the right. On phones, the header is listed at the top, with the text to the right of the image, and the child elements below.

Editorial

The EDITORIAL display mode displays album art and can include up to three lines of text. By default, it displays two lines: title and summary. Sonos app show the title and summary to the right of the album art.

Next steps

Learn more about how to customize your content in the Sonos app: