Add reporting

Sonos players can send reports to your service for certain actions. These reports may be useful to comply with monetization policies from content owners or to meet DMCA requirements. Report actions include:

• Final playback duration — The total aggregate time for which a player played a track.
• Periodic playback updates — The cumulative number of seconds for which a player played a track, sent at specific intervals.
• Implicit and explicit actions — How an action was initiated, for example, whether a user pressed play to start content, or whether it began playing because it was the next song in the queue.

Players send playback reports to your service

Sonos players send reports to your POST /timePlayed endpoint. Players don't send reports immediately, but can delay them. For example, periodic reports may be delayed by a few seconds after the interval. This is due to how Sonos implemented reporting on players.

Set up reporting for your integration

You can enable reporting for your integration using the integration submission form. The key endpoint is the Reporting Endpoint, where you'll receive reports about SMAPI content playback.

You can set up reporting using the following steps:

1. From your Dev Portal, navigate to your Dashboard.
2. Select the integration you want to implement reporting in.
3. In the Sonos Music API section, fill out the Reporting Endpoint field with a valid URL.

   📘

   All endpoints require the version number somewhere in the URL. The example in the Reporting Endpoint field uses v2, but you can also use the latest version of the cloud queue. See Cloud Queue API for details.

4. Click Save.

Once you have set up reporting in your sandbox integration, you can inform the Sonos player about your service. To do so, follow the steps under Activate your sandbox service.

Use the Localization Resources section to edit the strings that the Sonos app presents to the user that are specific to your service, such as error strings. See Strings and localization to read more about localization resources.

Receive final playback reports

Sonos players send the total aggregate time for which 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. For more details about skipped tracks, see the Playback actions and status changes section below. Sonos players send a final playback duration report after 30 minutes of no playback activity to indicate that playback has stopped. For a more granular report of play time, you can choose to receive periodic playback updates, described below.

Players send final playback reports by sending a POST /timePlayed request to your reporting endpoint. The type of report is "final". This report also includes the following fields:

• containerId — this is equivalent to the contextId, the parent container of the enqueued object. For example, the playlist, radio, or album containing the item. For single enqueued tracks, the containerId is the same as the track ID.
• durationPlayedMillis — the total duration of playback, in milliseconds. This is cumulative, including any scrub or seek operations within the track during a single playback, so this value may be greater than the duration of the track.
• positionMillis — the current playhead position at the time of the report.
• positionMillisAtSegmentStart — the playhead position at the start of the current segment. For example, this could contain the position where the user last paused.
• timeSincePlaybackMillis — the time in milliseconds since this track began playback. This value gives the you a reference for when playback started. This value reports the delta between when playback began and when the POST /timePlayed request was posted. This can be different from durationPlayedMillis due to pausing and resuming.

In POST /timePlayed v2.3, we added the following fields:

• error — indicates the “type” of error and associated “status” that prevented the speaker from initiating or interrupting playback. See the POST /timePlayed SMAPI error objects for details.
• reportId — a stable UUID in the canonical format that you may use to correlate periodic and final reports for a single logical track playback. Unlike the id field, this identifier changes on each logical playback of the track queue item. For example, you can use this attribute to differentiate reports for id 0 when Sonos plays a different item in between, such as when a user skips back to item id 0.

Examples

Examples show results for v2.1 and v2.3 cloud queues.

A final POST /timePlayed playback report for v2.1 sent by a player for a SMAPI track from an enqueued album playing on the Sonos queue.

{  
  "items":[  
    {  
      "containerId":"al:47",
      "durationPlayedMillis":28031,
      "mediaUrl":"x-sonosapi-hls-static:tr%3a541?sid=253&flags=32800&sn=46",
      "objectId":"tr:541",
      "positionMillis":28031,
      "positionMillisAtSegmentStart":0,
      "timeSincePlaybackMillis":28218,
      "type":"final"
    }
  ]
}

A final POST /timePlayed playback report for v2.3 with a reportId.

{
  "items": [
    {
      "reportId": "0e5614b9-fcc7-4eec-b087-1892b7e64fa6",
      "id": "this_is_the_cloud_queue_item_id",
      "mediaUrl": "http://media.host/path/12345.mp3",
      "queueVersion": "xyz",
      "contextVersion": "abc",
      "type": "final",
      "positionMillis": 500,
      "positionMillisAtSegmentStart": 0,
      "durationPlayedMillis": 500,
      "timeSincePlaybackMillis": 1250
    }
  ]
}

Receive periodic playback updates

By default, Sonos players send playback reports every 60 seconds. The report states the cumulative number of seconds that a Sonos group has played the track. This may be useful information for content licensing. The type of report is "update". When using this for SMAPI reporting, the reports object keys will be set to the following defaults:

• sendUpdateAfterMillis — Sonos players perform the default behavior when this key is omitted and send a playback report after the track has played for one second.
• periodicIntervalMillis — Players use the default value of 60 seconds.
• sendPlaybackActions — Set to false. Players do not send reports to account for actions that pause playback or skip to the next track.

Example

An update POST /timeplayed report for v2.0 sent by a player indicating that just over 60 seconds of a track has played (indicated by durationPlayedMillis) and playback started at an offset of 14 seconds (indicated by positionMillisAtSegmentStart).

{
  "items": [
    {
      "id": "<item-id>",
      "mediaUrl": "http://media-host.example.com/path/12345.mp3",
      "queueVersion": "xyz",
      "type": "update",
      "durationPlayedMillis": 61914,
      "timeSincePlaybackMillis": 63742,
      "positionMillis": 75000,
      "positionMillisAtSegmentStart": 14000
    },
    ...
  ]
}

Implicit and explicit actions

In addition to the reports above, you can find out how some actions occurred, whether the action was implicit or explicit.

• 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. To receive implicit or explicit actions, select "Support the ability to receive implicit or explicit actions for getMediaUri requests".

SMAPI reporting

❗

SMAPI reporting deprecated

Previously, the player sent reports using SMAPI requests. These are deprecated.

Please use the POST /timePlayed reporting endpoint described above. For historical purposes, this section describes the SMAPI requests.

If you implemented SMAPI requests for reporting, see the references below for how to set up the same reports using POST /timePlayed endpoints:

• setPlayedSeconds — see Receive final playback reports.
• reportPlaySeconds — see Receive periodic playback updates.
• reportPlayStatus — no longer available. See Add programmed radio for skip enforcement and Save & resume playback for pausing and resuming playback.

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. 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 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 Test 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: