Integrating your service favorites with Sonos

This page is no longer updated.

See Add favorites on the Sonos developer portal for the latest documentation.


Displaying your favorites

In order for the listener to browse and select their favorites, you provide access to the favorites from the top-level (root) container. The following screen shows an example of how a listener accesses favorites.

The following steps describe how to display in the Sonos app the listener's favorites from your service.

  1.  When the Sonos listener starts using your service or browses to the top of your service, sonos sends your service a getMetadata request for the top-level root of your containers. The following is a sample request for the root.
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <getMetadata xmlns="http://www.sonos.com/Services/1.1">
      <id>root</id>
      <index>0</index>
      <count>100</count>
    </getMetadata>
  </soap:Body>
</soap:Envelope>
  1. Return a favorites container with the other top-level item types in the getMetadata response. 
    The favorites is a container <itemType> with the <containsFavorite> element set to true.This tells the Sonos app to poll more frequently for changes to this container.
<soap:Envelope
    xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <getMetadataResponse
        xmlns="http://www.sonos.com/Services/1.1">
      <getMetadataResult>
        <index>0</index>
        <count>4</count>
        <total>4</total>
        <mediaCollection readOnly="false" userContent="true" renameable="false">
          <id>playlists</id>
          <itemType>playlist</itemType>
          <title>Playlists</title>
          <canScroll>false</canScroll>
          <canPlay>false</canPlay>
          <canEnumerate>true</canEnumerate>
          <albumArtURI>http://icons.com/playlists-icon.png</albumArtURI>
          ...   
        </mediaCollection>
        <mediaCollection>
          <id>favorites</id>
          <itemType>container</itemType>
          <title>My Acme Favorites</title>
          <containsFavorite>true</containsFavorite>
          <albumArtURI>http://icons.com/favorites-icon.png</albumArtURI>
          ...
        </mediaCollection>
        <mediaCollection>
          <id>new</id>
          <itemType>trackList</itemType>
          <title>New</title>
          <canPlay>false</canPlay>
          <albumArtURI>http://icons.com/new-icon.png</albumArtURI>
          ...
        </mediaCollection>
        <mediaCollection>
          <id>surprises</id>
           <itemType>container</itemType>
           <displayType>genreMood</displayType>
           <title>Surprises</title>
           <canPlay>false</canPlay>
          <albumArtURI>http://icons.com/surprises-icon.png</albumArtURI>
           ...
        </mediaCollection>
      </getMetadataResult>
    </getMetadataResponse>
...
  1. When the listener selects the favorites node, Sonos sends another getMetadata request that you respond to with the listener's favorites on your service.

 

Providing a hierarchy of favorites

While you could place albums, songs, and other items in the same <mediaCollection> under a node such as “favorites”,  you might not want to mix all the listener's favorites together. For example, to separate favorite songs from favorite albums, create a hierarchical organization beneath the "favorites" node such as the following:

My Acme Favorites <id>favorites
    /Albums/ <id>albumList
    /Songs/ <id>songList

If your service implemented this hierarchy, when the Sonos app sends an HTTP request with an album ID, your service should act on your favorites/albumList. When the Sonos app sends a similar request with a track ID, your service should act on your favorites/songList. If the listener browses into the favorites containerTo create the albumList and songList nodes, your service would return the following if the listener browsed into the favorites container:

<soap:Envelope
    xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <getMetadataResponse
        xmlns="http://www.sonos.com/Services/1.1">
      <getMetadataResult>
        <index>0</index>
        <count>2</count>
        <total>2</total>
        <mediaCollection>
          <itemType>container</itemType>
          <id>albumList</id>
          <title>My Favorite Albums</title>
          <containsFavorite>true</containsFavorite>
          ...
        </mediaCollection>
        <mediaCollection>
          <itemType>container</itemType>
          <id>songList</id>
          <title>My Favorite Songs</title>
          <containsFavorite>true</containsFavorite>
          ...
        </mediaCollection>
      </getMetadataResult>
    </getMetadataResponse>
   </soap:Body>
</soap:Envelope>

Be sure to update all favorites and the <favorites> value before responding to getLastUpdate requests as described in Synchronizing your favorites because all child nodes are governed by the parent node that is marked with <containsFavorites> set to true.