Related browse

The related browse action allows listeners to browse your service for music related to the current item. The following shows an example in the Info View of a related browse action.

The following steps describe how to implement the related browse action:

1. Define the text string in your i18next file that is to display in the Info View of the Sonos app. ("Related Songs").

   JSON

   {
       "en-US":{
         "common":{
             ...
             },
         "integration":{
           "RELATED_SONGS": "Related Songs"
           ...
         }
       },
   }
   

2. When the listener selects the ellipsis (...) to see the Info View, Sonos sends your service a getExtendedMetadata request. This example is for a track itemType.

   XML

   <s:Envelope  
    xmlns:s="<http://schemas.xmlsoap.org/soap/envelope/>">   
     <s:Header>  
    ...  
     </s:Header>  
     <s:Body>  
      <getExtendedMetadata xmlns="http://www.sonos.com/Services/1.1">  
        <id>t:123456</id>  
      </getExtendedMetadata>  
     </s:Body>  
   </s:Envelope>
   

3. Include all the custom action items for the Info View in your getExtendedMetadata response. To simplify this example we'll show a related browse custom action.

   XML

   <s:Envelope xmlns:s="<http://schemas.xmlsoap.org/soap/envelope/>" xmlns:ns="<http://www.sonos.com/Services/1.1>">   
      <s:Body>  
         <ns:getExtendedMetadataResponse>  
            <ns:getExtendedMetadataResult>  
               <ns:mediaMetadata>  
                  <ns:id>t:123456</ns:id>  
                  <ns:itemType>track</ns:itemType>  
                  <ns:title>This is the title</ns:title>  
                  <ns:genre>Alternative</ns:genre>  
                  <ns:mimeType>audio/mp3</ns:mimeType>  
                  <ns:trackMetadata>  
                     <ns:artistId>a:12345678</ns:artistId>  
                     <ns:artist>Example Artist</ns:artist>  
                     <ns:albumId>M:123456</ns:albumid>  
                     <ns:genre>Alternative</ns:genre>  
                     <ns:duration>236</ns:duration>  
                     <ns:albumArtURI><https://example.com/art_legacy.jpg></ns:albumArtURI>  
                     <ns:canPlay>true</ns:canPlay>  
                     <ns:canSkip>true</ns:canSkip>  
                     <ns:canAddToFavorites>true</ns:canAddToFavorites>  
                  </ns:trackMetadata>  
               <ns:mediaMetadata>  
               . . . Details for other custom actions in the Info View are not shown . . .  
               <ns:relatedBrowse>  
                  <ns:id>related-t:123456</ns:id>  
                  <ns:type>RELATED_SONGS</ns:type>  
               </ns:relatedBrowse>  
            </ns:getExtendedMetadataResult>  
         </ns:getExtendedMetadataResponse>  
      </s:Body>  
   </s:Envelope>
   

4. Note the following about relatedBrowse:

   Element	Description
   id	The value related-t:123456 identifies the service’s tracks related to the current track, t:123456. The pattern of these IDs is up to you.
   type	The value RELATED_SONGS corresponds to the JSON key in the i18next file above.

5. When a listener chooses a relatedBrowse action, the Sonos app sends a getMetadata request to your service using the given related browse id (related-t:123456).

6. Your service should respond to getMetadata with a mediaCollection of related songs.