Integrating a Music Service with Sonos

Overview

This document guides you through integrating your music service with Sonos. The table below summarizes the phases and time involved in making your service live on the Sonos app.

Phase Duration Description

Reading

A few hours to a day

Read through the documentation at API DOCUMENTS & TOOLS. Start with the Sonos System Overview to get familiar with Sonos products and how they work. Then read the Sonos Music API - Getting Started Guide to start learning about development.

Development

Depends on features

Develop the integration of your music service with Sonos. You should be well underway with your development before starting the next phase.

Registration

A few minutes

Register at Sonos Labs by entering basic contact information as a Sonos partner. Registering enables you to start the Submission phase.

Submission

1-2 hours

Specify a submission of your integration and submit it to Sonos. See below for a detailed description of this phase.

Application Review

6 weeks

Sonos may take up to 6 weeks to review your application. We will then either accept your application or reject it. After acceptance, Sonos will validate your integration.

Validation

6 weeks

Sonos performs a series of manual tests on your integration. After passing the manual tests, your integration can start a release phase.

Beta

6-8 weeks

Sonos releases your product in beta to allow customers to try it and provide feedback. You can also perform load testing and fine-tune your implementation. You approve the beta launch date. If you are an existing partner updating your service, we'll work with you to determine if you need a beta phase.

GA

1/2 hour

When your integration is complete and passes the beta, Sonos releases it to all Sonos users. This is your General Availability (GA) release.


For the Reading and Development phases, see the API DOCUMENTS & TOOLS documentation. Use this document to guide you through all the other phases of integration. Use the online Version Manager tool to fill out a series of forms with integration details. To fill these out, you may need input from people in different roles at your company:

  • A: COMPANY & LEGAL QUESTIONS - these are best answered by a program manager. The questions in this section relate to which countries your service is available.
  • B: TECHNICAL CONFIGURATION & TEST SETUP - these are best answered by your development manager. The questions in this section relate to URLs, XML integration files, and service capabilities. There are also some questions about user-facing items such as icons and text.
  • C: QUALITY ASSURANCE & PERFORMANCE - these are best answered by your QA and development managers. The questions relate to details about running the self-test suite. This includes a configuration file and successful test summary report.
  • D: MARKETING & OTHER GENERAL QUESTIONS - these are best answered by your program and marketing managers. The questions include details about your service's key features and branding.

Upgrades and changes

Upgrades and changes to your integration require a new submission version. These should take less time than your first one as you can start from a copy of a previous submission. Fill out a new version whenever you make a change, such as when you:

  • Add new regions.
  • Add a new description for your service.
  • Change your service name.
  • Add new features or capabilities.
  • Update logos, strings, presentation maps, and web assets.

Some updates may not need a full validation phase or beta release. For example, new global regions, logos, service descriptions, or name changes. Contact Sonos if you need to take your music service offline or remove an integration.

Register your organization at Sonos Labs

You do not need to register to develop a music service integration. But you do need to register to submit your music service to be a part of Sonos Labs. You can only submit integrations from one account. When you register, create an account that your company can use to submit integrations. You will use this account for upgrades and changes to your integrations as well. Follow these steps to register:

  1. Click the WELCOME link at the top right corner of the Sonos Labs site.
  2. Click CREATE ACCOUNT.
  3. Fill in the form completely to register as a partner. Note the following:
    • Be sure to include the Web Site URL from which customers access your service.
    • Let us know if your service has any limits or restrictions for streaming to an account. This is so that Sonos can plan and coordinate with you to integrate with your service's features.
    • The Create Username field uses the email you entered for the Primary Contact Email field. Change this field if you want to. It does not need to be an email address.
  4. When the CREATE ACCOUNT form is complete, click CONTINUE at the bottom of the page.
  5. Check your email for a message from SonosLabs@sonos.com.
    1. Open the email and find the instructions to authenticate your email address.
    2. Click the link in the email to authenticate, which logs you in to the Sonos Labs HOME page.
 

Submit an integration to Sonos

Sonos provides a wizard-like Version Manager tool to submit your integration. A submission consists of the following categories:

Completing a submission can take a significant amount of time, especially the first version. The Version Manager enables you to save your progress.

Start or Update a Submission

To work on a submission with the Version Manager, click the DEVELOP & SUBMIT link at the top of the Sonos Labs site.

Log in first
You must be a registered partner and logged into the Sonos Labs site to access the Version Manager. Go to the Sonos Labs WELCOME page to log in.
 

Add a new submission

Upgrade tip
If you are upgrading your music service integration, start with a copy of an existing submission.
 
  1. Click ADD A NEW VERSION.
  2. If you have not started a submission yet, go to A: COMPANY & LEGAL QUESTIONS and start entering details.
  3. If you have existing submissions, do one of the following:
    • Copy a submission: Click Iterate and enhance a previously existing version. Then select the version you want to copy from the drop-down.
    • Start a new empty submission: Click Create a brand new version.
  4. Click CREATE.
  5. Start entering details at A: COMPANY & LEGAL QUESTIONS.
 

Update an existing submission

  1. Under the ACTIONS column, click edit for the existing version you want to update.
  2. Click the down arrow next to the section you want to edit.
  3. Click EDIT for one of the following sections:
    • A: COMPANY & LEGAL QUESTIONS
    • B: TECHNICAL CONFIGURATION & TEST SETUP
    • C: QUALITY ASSURANCE & PERFORMANCE
    • D: MARKETING & OTHER GENERAL QUESTIONS
 

SUBMIT your integration

When you have completed entering the information, submit your integration to start the next phase.

Before you click SUBMIT

To ensure that we can process your submission:

  • Be sure that you have completed all required fields on your submission's pages.
  • Ensure your supplied graphics and other assets follow all guidelines. See B: TECHNICAL CONFIGURATION & TEST SETUP.
  • Your integration development must pass the Self-Test Suite. Sonos uses your test configuration file from the self-test to retest your integration. This should produce the same results as your summary report. Download the QUALITY & TESTING TOOLS SUITE, available at the bottom of the API DOCUMENTS & TOOLS page.

 

A: COMPANY & LEGAL QUESTIONS

Click Globally, no restrictions if your service is available within all countries. Or, click Specific Countries and select the countries where your service is available. The Licensee Name field uses the name you used to register. If appropriate, change it to your legal representation name.

B: TECHNICAL CONFIGURATION & TEST SETUP

Prerequisites
Your music service integration development should be well underway before you start this section.


The technical configuration section establishes the key settings for your music service. Many of these settings are visible to the end-user such as the service name, URLs, and some text and images. For example, to display your service in the Sonos app, a listener would click Add Music Services. Your service then appears (amongst others) in the Sonos Music Service Catalog.

The first set of fields on this page contain specific details about accessing and testing your integration development. These fields are also required when you test your service on a specific Sonos household. This testing process and the related fields are describe in Add your service with customSD.

Sonos no longer requires that you include the account information for the sub-section on SONOS ACCOUNT SYSTEM INFO.

For details about the fields in the sub-sections ICONS, UI TEXT, and SOCIAL MEDIA, see Digital Asset Guideline Overview and Listing your music service in the Service Catalog.

C: QUALITY ASSURANCE & PERFORMANCE

Prerequisites

Your music service integration development must have been fully tested and passed the latest Self-Test Suite. See the section QUALITY & TESTING TOOLS SUITE, which is available at the bottom of the page, API DOCUMENTS & TOOLS.

Be sure you use the latest version of the Self-Test Suite, available from the following downloadable compressed file: Python Self-Test Suite (zip file).


Include on this page URLs to your most recent successful Self-Test configuration file and Self-Test Summary Report HTML file. A sample of the Self-Test configuration file, smapiConfig.cfg, is available from the download. See Configuring the Self-Test Suite for details about completing the configuration file. For details about running the tests and generating the Self-Test Summary Report HTML file, see the Sonos Labs Self-Test Plan in Self-Test Overview (pdf download).

Please provide permanent test accounts for your service. These accounts will be used for continual monitoring and self-tests as well as verification of issues that may arise. If applicable, please provide accounts in different states. For example, provide an account level that is incompatible for use on Sonos, an expired account, and accounts at various subscription levels. This allows for more comprehensive service evaluation, monitoring and feedback.

Please provide permanent accounts for:

  • Monitoring & self-test usage (10 accounts)
  • Edge cases such as incompatible & expired accounts (1-3 accounts)
  • Customer care & manual verification (7 accounts)

Also include on this page details about your server architecture and performance of your service.

D: MARKETING & OTHER GENERAL QUESTIONS

Use this section to describe your service for customers. Sonos will use this information to describe your service on the music section of the Sonos website, http://www.sonos.com/streaming-music.

Application Review and Validation

After you submit your music service integration, Sonos communicates with you throughout the following steps to clarify and help you complete any deficiencies. Sonos does the following:

  1. Creates a basecamp account (https://basecamp.com/) to communicate with you as your submission is reviewed.
  2. Confirms all your submission's entries.
  3. Tests your music service using the self-test configuration file you provided. 
  4. Reviews branding and user-facing items such as logos.
  5. Accepts or rejects your submission. 
  6. After acceptance, Sonos performs a series of manual tests of your music service integration.

If your integration submission is rejected, Sonos communicates with you to fix the issues so you can resubmit, at which time your submission goes through steps 2 through 5 again. These steps are described in more detail below.

Confirm submission entries

The key items Sonos confirms from your submission are from the pages B: TECHNICAL CONFIGURATION & TEST SETUP and C: QUALITY ASSURANCE & PERFORMANCE. Key items reviewed include:

  • The string resource XML file is present and accessible.
  • The Presentation Map XML file is present and accessible.
  • All logos and UI items are present.
  • The self-test details are present.
  • The QA Sonos Support accounts are present
  • The Customer Care accounts are present

Run the Self-Test on your service

During your submission review, Sonos confirms that your test configuration is correct, which was entered and described in C: QUALITY ASSURANCE & PERFORMANCE. The following items are checked:

  • The configuration file is present and complete. 
  • The test accounts are present and available.
  • The test content is present.
  • The capabilities identified in the test configuration file match the capabilities that were checked and described in B: TECHNICAL CONFIGURATION & TEST SETUP.
  • The Self-Test Summary Report HTML file is present and contains no failures.

Sonos ensures we can run the Self-Test error-free using the configuration file you provided.

Sonos reviews your Branding

While we are reviewing your submission for development issues, we also consider your branding. We review the items on the following pages:

We review the logos, icons, and UI text strings in your integration. For example, we check the lengths of the text strings and URLs to ensure that they fit the displays in the Sonos app. We also review your marketing information for inclusion on Sonos web sites. For example, we list all services at http://www.sonos.com/streaming-music.

We review the co-branding page where customers sign-up for your service. This review ensures that your service looks consistent in Sonos apps and your app and web sites. Sonos works with you to develop this page. When Sonos users add your service in the Sonos app, the app loads this web page to so users can login or get a new account. This effort isn't necessary if your service allows anonymous users who do not have to login.

At some point during the validation process, you will need to provide discount information. Sonos offers a discount package for your employees to get Sonos products.

Sonos creates a frequently asked questions (FAQs) page about your service. We make this available within the Sonos FAQs page at https://sonos.custhelp.com/app/answers/list. For some examples see: 

Sonos approves or rejects your Submission

If we reject your submission, we'll explain the reasons in basecamp so you can update and resubmit it. Once we've accepted your submission, we'll perform manual testing.

Sonos performs Manual testing

Sonos runs a series of manual tests of your music service integration and sends you a summary. If some manual tests don't pass, you must fix the issues found in your integration. Then you must resubmit your application so that we can run the manual tests again. This process continues until your integration is ready for Beta. For a sample manual test summary of a music service submittal see ManualTestPlanResults.pdf (download)

During the manual testing process, Sonos may also prepare for your beta. If you are an existing partner and your submission is an update, you may not need a beta. We'll work with you to determine this on a case by case basis.

Beta release

Beta allows you to perform load testing and fine-tune your service. During the beta, Sonos customers test the service, provide feedback, and submit bugs. We'll work with you to set a beta launch date and coordinate with you to make it available to customers. The length of your beta depends on the complexity of your implementation. It can last eight weeks or more.

If you are an existing Sonos partner, Sonos decides if you need another beta cycle. Some examples of changes that may need another beta cycle include:

  • Significant changes such as an entire integration re-work.
  • Addition of a large number of new features or capabilities.
  • An earlier integration was particularly difficult. 

Sonos will continue to communicate with you through basecamp during the beta. We'll send you metrics on how often customers are using your service, as well as how many are using it. We'll also send you metrics on browse errors experienced by users. You should ensure that your service maintains the standards described in your service agreement. See the Sonos Escalation Process (PDF download) for an example.

When your service is in beta, Sonos adds an icon on your service logo to show that your service is in beta. Users can also view all services in beta with the beta filter. Your service will only be available for testing by users in the beta program. For instructions on how to join, see the FAQSonos Beta Programs. The beta icon disappears after a user adds your service.

Exiting the beta program is at Sonos’ discretion and is based on meeting error and usage rates. Sonos will coordinate with you to ensure these rates are adequate. Some factors that play a part in this decision are:

  • Number of users and active engagement
  • Service Performance
  • Feedback
  • Resolution of open issues

General Availability (GA) release

After a successful beta, Sonos will release your service for general availability (GA). This can occur as soon as 8 weeks after your beta. Sonos will work with you to set a GA date and coordinate with you on your basecamp account. The following key actions occur when we release your service for GA:

  • Your music service appears on the Sonos Music Menu with the beta icon removed from your logo.
  • Sonos coordinates with you to ensure all web assets are up to date and posts your logo to sonos.com.
  • Sonos coordinates with you for updates and then publishes your FAQ on the support site Sonos FAQs. See examples in the Branding review section of this document.
  • Sonos changes the name of your basecamp account to GA: Your-Service-Name