Sonos Developer

To add your own action to the Info View that displays text, use the relatedText element in your getExtendedMetadata response. Also use your strings.xml file to define the text string 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:

Here’s an example of the string in the en-US strings.xml file for the example above:

<string stringId="ABOUT_ARTIST">About the Artist</string>

1	<string stringId="ABOUT_ARTIST">About the Artist</string>

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.

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

<s:Envelope

xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">

<s:Header>

...

</s:Header>

<s:Body>

<id>track:123456</id>

</getExtendedMetadata>

</s:Body>

</s:Envelope>

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.

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

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

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.
When a user chooses a related text action, the Sonos app sends a getExtendedMetadataText request to your service using the given id and type.

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

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

<soap:Body>

<id>track:123456</id>

<type>ABOUT_ARTIST</type>

</getExtendedMetadataText>

</soap:Body>

</soap:Envelope>

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.

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

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

<soap:Body>

This is a basic description of this artist...

</getExtendedMetadataTextResult>

</getExtendedMetadataTextResponse>

</soap:Body>

</soap:Envelope>