Test your service

This explains how to test your service integration during development. Sections include:

Learn how to add your service to a specific player and perform tests by using the Sonos app and SoapUI. See a list list of tests to perform using the Sonos app with the SoapUI tool.

Test your service on Sonos with Custom SD

Use the custom service descriptor page on a player (customSD.htm) to add your SMAPI service to your Sonos system for testing. The capabilities on this form mirror the capabilities that you can make for your service in the Technical Configuration & Test Setup section of your service application in the Version Manager. See Add capabilities for details.

To add your service to your Sonos system:

  1. Find the IP address of one of your players. See Check my Sonos ID and which version my Sonos system is running for details.
  2. Enter this URL into a web browser:
    http://{IP address of Sonos player}:1400/customsd.htm
  3. Fill out the form with information that is relevant to your service and click Submit.
  4. On your Sonos app, select Add Music Services and add your service.

General items

General items on the Custom SD page.

Form field Description
SID An internal identifier for Sonos firmware. Valid values are 240-253, and 255 inclusive.
Service Name The name of your service. This name gets on the Add Music Services menu, when browsing, and in the universal search results.
Endpoint URL Enter the same endpoint as below. This field will soon be deprecated.
Secure Endpoint URL Sonos players and apps send requests to the secure endpoint. See the Sonos Music API reference pages for details. The SSL endpoint for your SMAPI service. This URL must be a valid hostname that DNS can resolve that matches your certificate. HTTPS is required. See security for details.

Note: For testing, you can enter the non-SSL endpoint, such as an IP address on your local network, but you’ll need a secure endpoint in order to submit your application.
Polling Interval The number of seconds between each Sonos poll request. Sonos firmware leverages the polling technique to check for updates in browse content. See getLastUpdate for details.

Authentication SOAP header policy

Sonos no longer supports new implementations using Session ID or Device Link for authentication. If your implementation currently uses these, you can still choose these options. For example, you may be testing an upgrade to your current service. If you’re creating a new service, choose anonymous or application link authentication. The authentication methods are summarized below. See Add authentication for details.

Authentication method Description
Session ID Not recommended. Use Application Link for more secure authentication. Session ID enables your service to grant Sonos a session ID, which Sonos then passes back to your service for validation.
Anonymous Sonos will not use any authentication method to access your service, thereby allowing any user access.
Device link This method has been replaced by browser authentication. Choose Application Link and configure browser authentication to enable users to enter their credentials in a web page.
Application link Sonos uses your mobile app or a browser to authenticate the user and authorize them to use their account in their household.

Strings table

The XML file to use for custom strings and localization. See Strings and Localization for details.

Form field Description
Version The version number of your strings table XML file, which should start at 1. When testing with customSD, you must increment this number for Sonos apps to pick up changes made to your strings table XML file. In production, let your Sonos representative know that we must increment this number.
Uri The URL where your strings.xml file is hosted.

Presentation map

The XML file to use for content display in Sonos apps. Required if you enabled the search capability. See Customize display for details.

Form field Description
Version The version number of your presentation map XML file, which should start at 1. When testing with customSD, you must increment this number for Sonos apps to pick up changes made to your presentation map XML file. In production, let your Sonos representative know that we must increment this number.
Uri The URL where your presentation map XML file is hosted.
Container type The location where the Sonos app displays your service in the Add Music Services menu.

  • If you select “Music Service,” the Sonos app displays your SMAPI Service in the top-level list of services in the Add Services wizard.
  • If you select “Sonos Sound Lab”, the Sonos app for desktop computers displays your service in a container called “Sonos Labs”, one level below the top-level Add Music Services list. In the Sonos app for mobile devices, this adds a preview tag to your logo in the Service Catalog.

Capabilities

See Add capabilities for details.

Test with the Sonos app

Use the Sonos app to manually test and verify portions of your implementation. See a PDF of sample tests here. Perform these tests after adding your service to your Sonos system. You can also use a tool like SoapUI to see the metadata exchange between your service and the Sonos app. We recommend that you run these tests before submitting your integration. See submit your content service for details. To run these tests, you need a Sonos app on a Mac, PC, Android, or iOS device, and at least one Sonos player, such as a Play:1. Here’s a list of some of the tests you can run. The tests are arranged by feature, so only run the tests that are applicable to your service.

Account management

  • Add a trial account.
  • Add supported accounts.
  • Add an unsupported account.
  • Add a deleted account.
  • Add a supported account that is expired.

Search

  • Verify search in all applicable containers.
  • Verify multi-library search (if applicable).
  • Verify incremental search functionality in all applicable containers. Every new character entered should process a new search.
  • Verify search functionality using special characters and accented characters in all applicable containers.
  • Verify any error messages returned in search results.
  • Verify artwork returned in search results.
  • Verify metadata returned in search results.

Browse

  • Click through to the end of each container. Successful completion requires no browse errors, timeouts, or corrupted data.
  • Verify that browsing happens within a reasonable timeframe.
  • Verify that the metadata returned within the browse containers is correct and includes album art URIs where applicable.
  • Verify that all content, including artists, album, track, and playlists match your app and website.
  • Verify the artwork renders correctly in browse containers.
  • Verify that all appropriate nodes are generated in a container.
  • Verify that pagination works in large containers.

Playlist editing using the Sonos app

  • Create a playlist from an album, track, or playlist.
  • Edit a playlist.
  • Remove a playlist.
  • Reorder a playlist.

Favorites

  • Add a favorite track.
  • Remove a favorite track.
  • Add a favorite album.
  • Remove a favorite album.
  • Check that favorites added or removed via your app or website are represented.
  • Ensure that updates happen in a reasonable timeframe.

Ratings

  • Verify selecting the positive rating button rates the content successfully.
  • Verify selecting the negative rating button rates the content successfully.
  • Verify the correct success message is shown when selecting the positive ratings button.
  • Verify the correct success message is shown when selecting the negative ratings button.

Dynamic ratings

  • Verify rating a track causes the ratings icon to change to match the rating.
  • Verify that re-rating a track causes the rating icon to update to match the new rating state.
  • Verify a previously rated track shows the current ratings state on the Now Playing screen when replayed.
  • Verify the correct messaging is shown when a track receives a positive rating.
  • Verify the correct messaging is shown when a track receives a negative rating.

Custom error handling

  • Verify the service is returning a custom error code when a specific error condition is met. Use a tool like SoapUI to do this verification.
  • Verify the Sonos app shows the correct custom error message when a specific error is met.

Test using SOAPUI

The following example uses SoapUI, but you can use any tool that can send a SOAP request and get a response.

  1. Create an initial project by importing the Sonos WSDL. This creates a list of Sonos SOAP actions such as search, getMediaMetadata, and getMetadata. Download the WSDL from SOAP requests and responses.
  2. Use the log file to identify the SOAP action type of the request in the Body (identified as <ns0:Body>). See the example log below.
  3. Copy the complete XML section starting with <?xml> and ending with </SOAP-ENV:Envelope>.
  4. Locate the SOAP action in SoapUI and paste the XML request from the previous step.
  5. Enter your test SMAPI endpoint in SoapUI.
  6. Set a user-agent in the HTTP header, such:
  7. User-Agent: Linux UPnP/1.0 Sonos/24.0-69180 (Self-Test).
  8. Send the SOAP request and wait for the response.

Next step

Go on to Submit your content service.