Sonos Developer

You can add to the Info View a URL Link using the open URL action. The open URL action provides listeners with a URL to open a Web page or a mobile app for iOS and Android platforms. For example, you might provide a URL to show an artist’s concert schedule and perhaps a way to buy tickets. The URL must use secure HTTPS, “https://”. The following figure shows an example of an open URL action.

When the listener selects the open URL action, Sonos opens the URL in a browser or into an iOS or Android app. The URL you provide can link into your iOS or Android apps, or other third party apps. For more details on constructing app URLs, see the following relevant links:

iOS: Support Universal Links in Apple’s App Search Programming Guide
Android: Handling Android App Links in Android’s developer docs

The following steps describe how to implement the open URL action:

Define the text string in your strings.xml file that is to display in the Info View of the Sonos app. For this example we use, “Concerts”.

<string stringId="CONCERTS_STRING">Concerts</string>

1

<string stringId="CONCERTS_STRING">Concerts</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 actions for the Info View in your getExtendedMetadata response. To simplify this example we’ll show only the open URL action.

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="http://www.sonos.com/Services/1.1">
   <s:Body>
      <getExtendedMetadataResponse>
         <getExtendedMetadataResult>
            <mediaMetadata>
               <id>track:123456</id>
               <itemType>track</itemType>
               <title>This is the title</title>
               <genre>Alternative</genre>
               <mimeType>audio/mp3</mimeType>
               <trackMetadata>
                  <artist>Example Artist</artist>
                  <genre>Alternative</genre>
                  <duration>236</duration>
                  <albumArtURI>https:example.com/art_legacy.jpg</albumArtURI>
                  <canPlay>true</canPlay>
                  <canSkip>true</canSkip>
                  <canAddToFavorites>true</canAddToFavorites>
               </trackMetadata>
            </mediaMetadata>
            <relatedActions>
                <action>
                   . . . Details of the action for favorites "Save to My Acme Music" in the Info View are not shown . . .
                </action>
                <action>
                    <id>concerts_action_id</id>
                    <title>CONCERTS_STRING</title>
                    <actionType>openUrl</actionType>
                    <openUrlAction>
                        <url>https://www.example.com/concerts/?artistId=a:12345678&amp;tracker=foo</url>
                    </openUrlAction>
                </action>
            </relatedActions>
            . . . Details for other custom actions in the Info View are not shown . . .
         </getExtendedMetadataResult>
      </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>

<id>track:123456</id>

<itemType>track</itemType>

<title>This is the title</title>

<genre>Alternative</genre>

<mimeType>audio/mp3</mimeType>

<artist>Example Artist</artist>

<genre>Alternative</genre>

<albumArtURI>https:example.com/art_legacy.jpg</albumArtURI>

</trackMetadata>

</mediaMetadata>

. . . Details of the action for favorites "Save to My Acme Music" in the Info View are not shown . . .

</action>

<id>concerts_action_id</id>

<title>CONCERTS_STRING</title>

<actionType>openUrl</actionType>

<url>https://www.example.com/concerts/?artistId=a:12345678&tracker=foo</url>

</openUrlAction>

</action>

</relatedActions>

. . . Details for other custom actions in the Info View are not shown . . .

</getExtendedMetadataResult>

</getExtendedMetadataResponse>

</s:Body>

</s:Envelope>

The relatedActions element contains an action sub-element to provide a URL to open from the Info View. The relatedActions element can contain multiple action sub-elements, each representing a different custom action. The action sub-elements include the following:

Element	Description
`id`	A unique ID for this action.
`title`	The value CONCERTS_STRING corresponds to this stringId value in the strings.xml file above.
`actionType`	This value for an open URL action must be openUrl.
`openUrlAction`	This contains a single <url> sub-element whose value is the URL the listener opens.
`showInBrowse`	(Optional) By default, the action displays when the user is in either the browse or now-playing mode. To restrict the display of this action to only the now-playing mode, set this value to `false`.

When a listener chooses an openUrl action, the Sonos app opens the provided URL.

See SMAPI Object Types for details.