Sonos Music API - Getting Started Guide

Reporting

You can receive reporting requests from Sonos players to keep track of actions. These reports may be useful to comply with monetization policies from content owners. This is an overview of the calls and how they relate to one another, common usage scenarios, common issues, and difficult cases such as reporting for HLS streams.

Overview

Reports can tell you:

  • The total aggregate time for which a player played a track.
  • The cumulative number of seconds for which a player played a track (sent at specific intervals).
  • When users chose to stop or pause playback.
  • When users chose to skip tracks.
  • When an account has been successfully added to a Sonos system.
  • When there have been radio stream failures.

Sonos players send the following reporting-related requests to your service, provided that you have chosen to receive them (see below for details):

  • setPlayedSeconds - Sends play time reporting. Useful for finding out how long a player played a track. The player sends this notification at the end of track playback whether playback ended as the result of a skip, direct user action switching playback to another source, natural end of playback, end of queue, or other action. Sonos players send a final setPlayedSeconds report after 30 minutes of no playback activity to indicate that playback has stopped. See reportPlaySeconds for a more granular report of play time.
  • reportAccountAction - Reports when an account has been successfully added to the Sonos system for your service.
  • reportPlaySeconds - At specified intervals, reports the cumulative number of seconds played of a track. This report may be useful to keep track of the number of seconds that a track has been played, for licensing purposes.
  • reportPlayStatus - Reports on play status changes. Useful for discovering when a track has been skipped or paused.
  • reportStatus - Reports on radio stream failures.

You will not get reports immediately on all change events. Players can delay periodic reporting by a few seconds after the interval due to how we have implemented reporting.

Implicit and Explicit actions

In addition to the reports above, you can find out how some actions occurred by turning on the "Support the ability to receive implicit or explicit actions for getMediaUri requests" capability.

  • An implicit action is an action without user input, such as when a Sonos player plays the next track in the queue.
  • An explicit action is a user action, such as when a user presses Play on a player.

Players report these actions as part of the action parameter of the getMediaURI request, as well as the number of seconds since the last queue-based activity, in the secondsSinceExplicit parameter.

Reporting Context

You can receive the context of where a track was played from, such as the playlist or album. For example, if a user browsed to an album and queued the album container, the contextId would be the album container ID. Select the "Add play context to reporting" capability to do so.

The <id> value sent in the report request would be the unique ID of the played track, stream, or show within the stream if this data is being sent. In the case where the user played a single track or stream, this ID would be the same as the contextId. Likewise, if no ID is being sent for the show or currently playing track in a live stream, the ID and the contextId would be the same. The ID for a programmed radio station will appear as the contextId for all of the tracks played on that station.

Turn on REPORTING capabilities

In order for Sonos players to send status reports to your service, you must enable the appropriate status reporting capabilities. When testing your service, use the customSD.htm page on a player to turn on reporting capabilities, as described in Add your service with customSD. When submitting your service to Sonos, use the Version Manager to enable reporting capabilities, as described in B: Technical configuration & test setup.

Enable the following reporting features by selecting the capability indicated:

  • To enable setPlayedSeconds, select "Playback duration logging at track end".
  • To enable reportAccountAction, select "Account Logging".
  • To enable reportPlaySeconds and reportPlayStatus, select "Playback event logging during track play".
  • To receive implicit or explicit actions, select "Support the ability to receive implicit or explicit actions for getMediaUri requests".
  • To receive the context from which a track played, select "Add play context to reporting".

sample Reporting Workflow

If you have turned on all of the reporting options (including the ability to receive implicit or explicit actions), when Sonos players play music, they call reportPlaySeconds to send play position information to your service. The Sonos player continues to call reportPlaySeconds regularly until the user decides to play something else or pauses playback.

If the user explicitly selects the Sonos app's pause button, the Sonos player calls reportPlayStatus to report the paused status to your service.

If the user presses play to continue playback, when the current track ends and a new track begins, the Sonos player calls setPlayedSeconds and reports the total amount of time the now completed track has played. This occurs no matter how the track changes, such as when a track completes playing, when a user chooses to skip to the next chapter of a book, or when a user starts to listen to something else.

If the user seeked to a new position in the track, the player sends the EXPLICIT:SEEK value in the action parameter of the getMediaURI request.

Sample Reporting scenario

Here's a scenario and the reports sent by players for a set of tracks:

Time

Actions and events

Reporting requests and responses

00:00

The user starts playing a set of tracks:

  • Track A, which is 90 seconds long,
  • Track B, 120 seconds long,
  • and Track C, 180 seconds long.

 

00:01

Track A plays for 1 second.

The player sends a reportPlaySeconds request at a seconds value of '1'.

00:32

Track A is currently playing for at least 30 seconds.

If you set the reportPlaySeconds interval to 30 seconds, the player sends a reportPlaySeconds request at about this time.

These requests won't be sent at exactly every 30 seconds, due to how we have implemented reporting on players, but they will accurately reflect the number of seconds played. For example, you may get one report at 31 seconds, and the next at 63 seconds.

01:30

Track A ends and Track B begins playing immediately after.

The player sends a setPlayedSeconds request for Track A at the end of the track that indicates the track played for 90 seconds with no skips or seeks.

01:31

Track B plays for 1 second.

The player sends a reportPlaySeconds request when the stream starts playing track B, after at least 1 second of playback.

02:05

At 35 seconds into track B, the user seeks back 15 seconds and continues playing.

The player sends a reportPlaySeconds request for Track B after about 30 seconds.

Since you've set the reportPlaySeconds interval to 30 seconds, you will see multiple reportPlaySeconds requests during the time when track B is playing. 

03:45

Track B ends and Track C begins playing immediately after.

The player sends a setPlayedSeconds request for Track B at the end of the track, indicating that the track played for 135 seconds, even though the track was only 120 seconds long. This is due to the user seeking back 15 seconds in the track.

03:46

Track C plays for 1 second.

The player sends a reportPlaySeconds request when the stream starts playing Track C after at least 1 second of playback.

04:00

The user pauses track C.

The player sends a reportPlayStatus request indicating that playback was paused.

34:00

Track C has been paused for 30 minutes.

The player sends a final setPlayedSeconds request for Track C that indicates that the track played for 1 second.