Integrating your service favorites with Sonos

This page is no longer updated.

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


Adding and removing favorites

Whether the listener is browsing your content or viewing the current playing item, they add or remove a favorite from the Info View. You provide the listener with HTTP request actions to add or remove favorites in your responses to getExtendedMetadata. Then, when the user chooses the action from the Info View, Sonos makes the HTTP REST request to your service, which implements the method to add or remove the favorite. You should become familiar with the Info View by reading the introduction to Customizing listener actions in the Info View

We'll describe the following tasks:

  1. Provide HTTP request actions for the Info View
  2. Implement a REST method to add a favorite
  3. Implement a REST method to remove a favorite

 

Provide HTTP request actions for the Info View

You will need to provide the listener with a control to add or remove the current item they are viewing or listening to. Do so by including the HTTP request action in your response to getExtendedMetadata, when the listener uses the Info View. The following images are examples of the Info View for the situations when the current item is not a favorite and when it is a favorite.

The following steps describe how to set the Info View:

  1. Define the text strings for favorites.
    Define the text strings in your strings.xml file that will display for the HTTP requests in the Info View. You can also define optional success and failure error strings. The stringId values as shown in the following example are up to you. These string IDs will be referenced in the following sections. For more about the strings.xml file, see Strings and Localization
...
<string stringId="ADD_MUSIC">Save to My Acme Music</string>
<string stringId="DELETE_MUSIC">Remove from My Acme Music</string>
...
<string stringId="ADD_SUCCESS">Saved to your Acme Music favorites.</string>
<string stringId="ADD_FAILED">Failed to save to your Acme Music favorites.</string>
<string stringId="DELETE_SUCCESS">Removed from your Acme Music favorites.</string>
<string stringId="DELETE_FAILED">Failed to remove from your Acme Music favorites.</string>
...
  1. Sonos sends a getExtendedMetadata request.
    When the listener is browsing a container or listening to a track or station, they can select the ellipse (...) to view more about the current container or item. When this happens, Sonos sends your service a getExtendedMetadata request. The following request example is for a track. 
<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>tr:15</id>
    </getExtendedMetadata>
  </s:Body>
</s:Envelope>
  1. your service checks to see if the current item (tr:15 in this example) is already in the listener's favorites.
  2. Your service responds to getExtendedMetadata.
    Use an HTTP request action in your getExtendedMetadata response to implement adding or removing a favorite. 

For details about HTTP request actions, see also Implementing HTTP REST Requests

Provide an HTTP request action to add a favorite

If the listener's current item is not in their favorites, provide in your getExtendedMetadata response an HTTP request to add the item to favorites. Be sure to include all the custom actions for the Info View in your response. To simplify this example, we show only the HTTP request action.  

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <getExtendedMetadataResponse xmlns="http://www.sonos.com/Services/1.1">
            <getExtendedMetadataResult>
                <mediaMetadata>
                    <id>tr:15</id>
                    <itemType>track</itemType>
                    <title>Man in the Mirror (2003 Edit)</title>
                    <mimeType>audio/mp3</mimeType>
                    <trackMetadata>
                        <artistId>QltoGrsHWgT0yA</artistId>
                        <artist>Michael Jackson</artist>
                        <composer/>
                        <albumId>fYpMChhFbjwT0yA</albumId>
                        <album>Number Ones</album>
                        <genre1980s Pop</genre>
                        <duration>303</duration>
                        <albumArtURI>http://cdn.acme.com/fYpMChhFbjwT0yA</albumArtURI>
                        <canPlay>true</canPlay>
                    </trackMetadata>
                    . . .
                </mediaMetadata>
                <relatedActions>
                    <action>
                        <id>add_item_to_favorites_id</id>
                        <title>SAVE_MUSIC</title>
                        <actionType>simpleHttpRequest</actionType>
                        <simpleHttpRequestAction>
                            <url>https://192.168.0.10:8223/v2/favorites?itemId=tr:15</url>
                            <method>PUT</method>
                            <httpHeaders>
                                <httpHeader>
                                    <header>clientid</header>
                                    <value>sonos-to-acme-client</value>
                                </httpHeader>
                            </httpHeaders>
                            <refreshOnSuccess>true</refreshOnSuccess>
                        </simpleHttpRequestAction>
                        <showInBrowse>true</showInBrowse>
                        <failureMessageStringId>ADD_FAILED</failureMessageStringId>
                    </action>
                . . . Details of other actions not shown . . .
                </relatedActions>
                . . . Details for other custom actions in the Info View not shown . . .
            </getExtendedMetadataResult>
        </getExtendedMetadataResponse>
    </soap:Body>
</soap:Envelope>

Note the following when you provide <action> and its sub-elements for an HTTP request action to add a favorite. For complete details see relatedActions.  

  • The <title> value SAVE_MUSIC corresponds to a stringId value in your strings.xml file.
  • The <actionType> value for an HTTP request action must be simpleHttpRequest.
  • The <simpleHttpRequestAction> element requires the following:
    • <url> - The URL of the HTTP REST request to your service. 
    • <method> - The HTTP method to execute on your service. Use PUT to add a favorite.

Provide an HTTP request action to remove a favorite

If the listener's current item is in their favorites, provide in your getExtendedMetadata response an HTTP request to remove the favorite. Be sure to include all the custom actions for the Info View in your response. To simplify this example, we show only the HTTP request action.  

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <getExtendedMetadataResponse xmlns="http://www.sonos.com/Services/1.1">
            <getExtendedMetadataResult>
                <mediaMetadata>
                    <id>tr:15</id>
                    <itemType>track</itemType>
                    <title>Man in the Mirror (2003 Edit)</title>
                    <mimeType>audio/mp3</mimeType>
                    <trackMetadata>
                        <artistId>QltoGrsHWgT0yA</artistId>
                        <artist>Michael Jackson</artist>
                        <composer/>
                        <albumId>fYpMChhFbjwT0yA</albumId>
                        <album>Number Ones</album>
                        <genre1980s Pop</genre>
                        <duration>303</duration>
                        <albumArtURI>http://cdn.acme.com/fYpMChhFbjwT0yA</albumArtURI>
                        <canPlay>true</canPlay>
                    </trackMetadata>
                    <dynamic>
                        <property>
                            <name>ratings</name>
                            <value>0</value>
                        </property>
                    </dynamic>
                </mediaMetadata>
                <relatedActions>
                    <action>
                        <id>remove_item_from_favorites_id</id>
                        <title>DELETE_MUSIC</title>
                        <actionType>simpleHttpRequest</actionType>
                        <simpleHttpRequestAction>
                            <url>https://192.168.0.10:8223/v2/favorites?itemId=tr:15</url>
                            <method>DELETE</method>
                            <httpHeaders>
                                <httpHeader>
                                    <header>clientid</header>
                                    <value>sonos-to-acme-client</value>
                                </httpHeader>
                            </httpHeaders>
                            <refreshOnSuccess>true</refreshOnSuccess>
                        </simpleHttpRequestAction>
                        <showInBrowse>true</showInBrowse>
                        <failureMessageStringId>DELETE_FAILED</failureMessageStringId>
                    </action>
                . . . Details of other actions not shown . . .
                </relatedActions>
                . . . Details for other custom actions in the Info View not shown . . .
            </getExtendedMetadataResult>
        </getExtendedMetadataResponse>
    </soap:Body>
</soap:Envelope>

Note the following when you provide <action> and its sub-elements for an HTTP request action to remove a favorite. For complete details, see relatedActions.  

  • The <title> value DELETE_MUSIC corresponds to a stringId value in your strings.xml file.
  • The <actionType> value for an HTTP request action must be simpleHttpRequest.
  • The <simpleHttpRequestAction> element requires the following:
    • <url> - The URL of the HTTP REST request to your service. 
    • <method> - The HTTP method to execute on your service. Use DELETE to remove a favorite.
  • (Optional) Set the <showInBrowse> value to true if you want the listener to be able to remove a favorite either when browsing or playing the item in the Sonos app. Set this value to false if you do not want the listener to be able to remove the favorite when browsing.

 

Implement a REST method to add a favorite

The following steps describe how to add a favorite on your service when the listener has chosen the HTTP request action from the Sonos Info View.

  1. Sonos sends the HTTP REST request using the PUT method and URL you provided in your getExtendedMetadata response. 
  2. Sonos also includes the current authentication token in an Authorization header as an OAuth Bearer token. For example: 
PUT https://192.168.0.10:8223/v2/favorites?trackId=tr:15
Host: music.acme.com
clientid: sonos-to-acme-client
Authorization: Bearer 614e6c9ce07be03ece09a8639ea40dcbd

For more about authorization and authentication tokens, see Processing authentication tokens for API requests.

  1. Your service implementation of the REST API adds the item to the listener's favorites list.
  2. Your service sends a response to the Sonos app that provides a new action in the Info View that allows the listener to change their mind and remove the favorite if they wish.
HTTP/1.1 201
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Connection: close
 
{
    "relatedActions": [
        {
            "actionType": "simpleHttpRequest",
            "id": "remove_item_from_favorites_id",
            "title": "DELETE_MUSIC",
            "simpleHttpRequestAction": {
                "httpHeaders": [
                    {
                        "name": "clientid",
                        "value": "sonos-to-acme-client"
                    }
                ],
                "method": "DELETE",
                "refreshOnSuccess": true,
                "url": "https://192.168.0.10:8223/v2/favorites?itemId=tr:15"
            },
            "showInBrowse": true,
            "successMessageStringId": "DELETE_SUCCESS",
            "failureMessageStringId": "DELETE_FAILED"
        },
        {
            "actionType": "openUrl",
            "failureMessageStringId": "OPEN_URL_ACTION_FAILED",
            "id": "concerts_action_id",
            "openUrlAction": {
                "url": "https://www.acme.com/concerts/?artistId=a:12345678&amp;tracker=foo"
            },
            "showInBrowse": true,
            "title": "CONCERTS_STRING"
        }
    ],
    "successMessageStringId": "ADD_SUCCESS"
}

The JSON relatedActions object provides a new HTTP request to remove the favorite that was just added as well as any other related actions you might require. See The relatedActions structure for full details. Note the following:

First action

  • The title value, DELETE_MUSIC, corresponds to the stringId value in your strings.xml file.
  • The simpleHttpRequestAction can include the following in any order:
    • method - The required HTTP method to execute for the new HTTP action. Use DELETE to remove a favorite.
    • url - The required URL of the new HTTP request that Sonos would send if the listener decides to selects the new HTTP action.
    • refreshOnSuccess - (Optional) Set this option to true so that the Sonos app will send a request to update the current container after removing the item. 
  • (Optional) Use a showInBrowse value of true if you want the listener to be able to remove a favorite when browsing their favorites from the Sonos app. 
  • (Optional) you can supply string ID values for successMessageStringId and failureMessageStringId that Sonos would display to the listener depending on the results of the new HTTP request. The values correspond to stringId values in your strings.xml file.

Second action

  • (Optional) An openUrl action is included in this example. You can include more than one action in your response to the original HTTP request. See Providing listeners with a URL to open for details about this action.
  • (Optional) This final successMessageStringId refers to a success message for the original add favorite HTTP request. This message would override a <successMessageStringId> value if it was supplied in the original getExtendedMetadata response.

Implement a REST method to remove a favorite

The following steps describe how to remove a favorite from your service when the listener has chosen the HTTP request action from the Sonos Info View.

  1. Sonos sends the HTTP REST request using the DELETE method and URL you provided in your getExtendedMetadata response. 
  2. Sonos also includes the current authentication token in an Authorization header as an OAuth Bearer token. For example: 
DELETE https://192.168.0.10:8223/v2/favorites?trackId=tr:15
Host: music.acme.com
clientid: sonos-to-acme-client
Authorization: Bearer 614e6c9ce07be03ece09a8639ea40dcbd

For more about authorization and authentication tokens, see Processing authentication tokens for API requests.

  1. Your service implementation of the REST API removes the item from the listener's favorites list.
  2. Your service sends a response to the Sonos app that provides a new action in the Info View that allows the listener to change there mind and add the favorite back if they wish. 
HTTP/1.1 201
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Connection: close
 
{
    "relatedActions": [
        {
            "actionType": "simpleHttpRequest",
            "id": "add_item_to_favorites_id",
            "title": "SAVE_MUSIC",
            "simpleHttpRequestAction": {
                "httpHeaders": [
                    {
                        "name": "clientid",
                        "value": "sonos-to-acme-client"
                    }
                ],
                "method": "PUT",
                "refreshOnSuccess": true,
                "url": "https://192.168.0.10:8223/v2/favorites?itemId=tr:15"
            },
            "showInBrowse": true,
            "successMessageStringId": "ADD_SUCCESS",
            "failureMessageStringId": "ADD_FAILED"
        },
        {
            "actionType": "openUrl",
            "failureMessageStringId": "OPEN_URL_ACTION_FAILED",
            "id": "concerts_action_id",
            "openUrlAction": {
                "url": "https://www.acme.com/concerts/?artistId=a:12345678&amp;tracker=foo"
            },
            "showInBrowse": false,
            "title": "CONCERTS_STRING"
        }
    ],
    "successMessageStringId": "DELETE_SUCCESS"
}

The JSON relatedActions object provides a new HTTP request to add the favorite that was just removed as well as any other related actions you might require. Note the following about the relatedActions structure:

First action

  • The title value, ADD_MUSIC, corresponds to the stringId value in your strings.xml file.
  • The simpleHttpRequestAction can include the following in any order:
    • method - The required HTTP method to execute for the new HTTP action. Use PUT to remove a favorite.
    • url - The required URL of the new HTTP request that Sonos would send if the listener decides to selects the new HTTP action.
    • refreshOnSuccess - (Optional) Set this option to true so that the Sonos app updates the current container after adding the item. 
  • (Optional) Use a showInBrowse value of false if you don't want to show this to the listener when they browse their favorites from the Sonos app. If the listener is browsing favorites, it would make little sense to add the favorite back again.
  • (Optional) you can supply string ID values for successMessageStringId and failureMessageStringId that Sonos would display to the listener depending on the results of the new HTTP request. The values correspond to stringId values in your strings.xml file.

Second action

  • (Optional) An openUrl action is included in this example. You can include more than one action in your response to the original HTTP request. See Providing listeners with a URL to open for details about this action.
  • (Optional) This final successMessageStringId refers to a success message for the original add favorite HTTP request. This message would override a <successMessageStringId> value if it was supplied in the original getExtendedMetadata response.