Account matching

Account matching is an important part of the Direct Control experience. It enables continuity of control so that your app and the Sonos app can play music in a Sonos household. See the sound experience guidelines for details.

Sonos owners can add accounts for many different music services to their household. People in the household can also add their own accounts. In one household, there may be several accounts configured for the same music service. Account matching enables your integration to use these accounts for authentication and playback. It also enables Sonos to create guest accounts for your integration to use for playback.

Account matching offers flexibility

Account matching offers flexibility for your service and Sonos listeners. With account matching enabled:

• Your implementation can use the same infrastructure as the Sonos app to play content. This is true whether a user started playing content from a Sonos app or your app.
• Sonos owners can personalize their content regardless of how they started it. They can use the Sonos app or your app. Personalization options include adding content as a favorite or to a playlist. More personalization features will be offered in future releases.
  • They can use the Sonos app to add content as a Sonos favorite or to a Sonos playlist.
  • They can use the Sonos app or your app to add content to a playlist on your music service.
  • Likewise, they can use either app to add content as a favorite on your service.
• Guests can play content on Sonos systems using your SMAPI infrastructure. They can do so even if the household owners don't have accounts with your service. Sonos owners have limited personalization options available for this type of content. They can't add music as a Sonos favorite or to a Sonos playlist. But they can search their existing services for it. And they can add your service to their Sonos household to gain personalization features.
• When guests have accounts with your music service and Sonos owners do as well, people can share music. When a guest plays music from your app, the Sonos owner can add that music to a favorite or playlist for later.
  • They can use the Sonos app to add it as a favorite to their account on your music service or as a Sonos favorite.
  • They can use the Sonos app to add it to a playlist in their account on your music service or to a Sonos playlist.

How Sonos uses accounts

If the Sonos owner or user has an account with your service, they can add it to the household using the Sonos app. Sonos uses SMAPI for communications between the household and your service. With account matching, Sonos listeners can use their own accounts for playback. If they don't have an account, Sonos will create a guest account to provide access. See details on this process below.

Listeners add their accounts using the Sonos app

Listeners add their accounts for your music service to their Sonos household using the Sonos app. The Sonos player stores this account and distributes it to the other players in the household.

Sonos apps and players use SMAPI for content and playback

Sonos players use SMAPI to request, play, and report on content from your music service. Sonos apps use it to display music service content. SMAPI includes authentication methods to secure your content.

Listeners play music using their accounts

Your service can stream content to Sonos players and listeners can choose how to control it. Sonos owners or guests can use the Sonos app or your app to control the music in a household. When the user plays music from your app, presumably they use their own account. Sonos players either find a match for that account or create a guest account for playback.

User experience of account matching

Here's how listeners would experience account matching in the Sonos app.

Sonos attributes content to your service in the Sonos app

When playing content from your service using Direct Control, the Sonos app attributes content from your service with your service logo.

Sonos owners with an account have personalization options

If the Sonos owner or a guest starts music with your Direct Control app and the owner also has an account with your service in their household, people in the household can use the Sonos app to choose personalization options for this content. For example, they can touch the three dots next to the song on the Now Playing and choose options for your music service, if you have enabled them, such as:

• Add song to a playlist on your music service.
• Start a radio station based on the song.
• Save to or remove from their favorites on your music service.
• Browse Album or Artist information.
• Rate a song (only if Sonos is playing the music from the same account as the one on the household).

Sonos owners can choose options for their Sonos accounts

They can also choose options for Sonos, such as:

• Add song to Sonos Favorites.
• Add Song to Sonos Playlist.
• Search for this song.
• Share this song.

Sonos owners with no account have limited options

If the guest starts music with your Direct Control app and the owner has not signed up with your service in their household, people in the household have limited options for this content in the Sonos app. For example, they can touch the three dots next to the song on the Now Playing screen and choose to:

• Search for the song in their existing local or music service libraries.
• Share the song.

Prerequisites for implementation

In order to use account matching, you need an existing SMAPI implementation to use for authorization and content. At the minimum, you should implement:

• Support for the userInfo object. The player stores the userInfo object and uses it for matching.
  • When the user adds an account for your service, Sonos gets the userInfo object from your getDeviceAuthToken response and stores it. Add the userInfo object to the getDeviceAuthToken response.
  • When a guest uses your app to play content on Sonos, the player gets the elements of the userInfo object in the match command (the match command contains a deconstructed version of the userInfo object).
  • Players call getUserInfo to populate the hashed user info for pre-existing accounts. For example, an owner may have added an account to their household before you implemented userInfo. Therefore, you must implement getUserInfo.
  • Enable the userInfo capability for your service. See Test your service for details.
• Authentication. At the minimum, implement Add browser authentication to authenticate Sonos listeners.
• Music playback using a music service endpoint and the getMediaURI method to serve static content.
• Info view using getExtendedMetadata and getExtendedMetadataText methods to display additional information about tracks. See Add actions for details.
• A cloud queue to serve the list of tracks to Sonos players. See our cloud queue sample server for a sample implementation and Play audio for details about cloud queues.
• You also need to know your service ID. When testing, this is the "SID" that you enter on the customSD form when adding your service to your Sonos system for testing. See Test your service for details. For production, you can get your service ID from Sonos during the integration process. See Submit your service for details.

Account matching workflow

The following workflow shows an overview of account matching.

Workflow details

1. In your app, the user selects a Sonos player for playback.
2. Your app sends a match command to the Sonos player.
   1. You supply a hashed user ID and a nick name for the account.
   2. Include the service ID from Sonos or as entered on a customSD page when testing your implementation on a single household.
   3. You supply the linkCode. You can use the same linkCode generation mechanism that you use for your getDeviceAuthToken response. Sonos uses this method to supply the linkCode to listeners when they add your music service in the Sonos app. We've extended this method to use for account matching as well.
3. The player uses the hashed ID to see if it already has a record of the account.
4. If the player does have a record of the account:
   1. And it is not a guest account, it responds to the match command with a number of parameters, specifically, the Sonos account ID and an indication that the account is not a guest account.
   2. And it is a guest account, it responds with the above and an indication that the account is a guest account. Guest accounts are cached. Sonos players recognize listeners with guest accounts. So if a user with a guest account returns to a household, Sonos responds to the match command with the guest account ID.
5. If the player does not have a record of the account:
   1. The player authorizes the account through SMAPI by sending a getDeviceAuthToken request using the linkCode you provided in the match command.
6. Your service should send back a response to the getDeviceAuthToken request that includes the userInfo object with the hashed ID and nick name matching the one sent you sent in the match command.
7. The player then adds this as a guest account.
8. The player responds to your match request with the account ID for the guest account and an indication that the account is a guest account.
9. To play the music on Sonos after the account has been matched, call createSession using the account ID.
10. The player sends a createSession response.
11. Your app should then call loadCloudQueue with the session ID and URL to the cloud queue.
12. The player sends a loadCloudQueue response.
13. The player requests a window of tracks from your cloud queue.
14. Your cloud queue sends a response with a window of tracks referencing the MusicObjectId for each track.
15. The player sends a getMediaURI request to your server using the track ID from the MusicObjectId.
16. Your server responds with the URI of the track. If you set playOnCompletion to true in your loadCloudQueue request, the track starts playing immediately. Otherwise, you can send a play command to the player to start playing the track.

Send linkDeviceId in match

You can also send the linkDeviceId in the match command. The player sends this back in the getDeviceAuthToken request, along with the linkCode. Use this to send a private identifier to prevent token phishing.

Setting up your server

SMAPI uses SOAP and the cloud queue is RESTful. You may want to set up your implementation with two different entry points and handlers that respond to each type of communication.