Related text

To add your own action to the Info View that displays text, use the relatedText element in your getExtendedMetadata response. Also use your localization file to define the text shown in the Info View of the Sonos app. The following figure shows an example of a related text action.

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

1. Here's an example of the text in the i18next file for the example above:

   JSON

   {
       "en-US":{
         "common":{
             ...
             },
         "integration":{
           "ABOUT_ARTIST": "About the Artist"
           ...
         }
       },
   }
   

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 item.

   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>track: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 the related text 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>track: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>  
               . . . Details for other custom actions in the Info View are not shown . . .  
               <ns:relatedText>  
                  <ns:id>track:123456</ns:id>  
                  <ns:type>ABOUT_ARTIST</ns:type>  
               </ns:relatedText>  
              . . . Details for other custom actions in the Info View are not shown . . .  
            </ns:getExtendedMetadataResult>  
         </ns:getExtendedMetadataResponse>  
      </s:Body>  
   </s:Envelope>
   

4. The type value in the relatedText element corresponds to a stringId of the same ID in your strings.xml file. This string is what displays in the Info View of the Sonos app.

5. When a user chooses a related text action, the Sonos app sends a getExtendedMetadataText request to your service using the given id and type.

   XML

   <soap:Envelope xmlns:soap="<http://schemas.xmlsoap.org/soap/envelope/>">   
     <soap:Body>  
      <getExtendedMetadataText xmlns="http://www.sonos.com/Services/1.1">  
        <id>track:123456</id>  
        <type>ABOUT_ARTIST</type>  
      </getExtendedMetadataText>  
      </soap:Body>  
   </soap:Envelope>
   

6. Your service should return the getExtendedMetadataText response containing the text to display. For example, when a user chooses About the Artist, your service would return a text description of that artist.

   XML

   <soap:Envelope xmlns:soap="<http://schemas.xmlsoap.org/soap/envelope/>">   
     <soap:Body>  
      <getExtendedMetadataTextResponse xmlns="http://www.sonos.com/Services/1.1">  
        <getExtendedMetadataTextResult>  
          This is a basic description of this artist...  
        </getExtendedMetadataTextResult>  
      </getExtendedMetadataTextResponse>  
     </soap:Body>  
   </soap:Envelope>