reports object

Added in v2.1

Key	Type	Value
`sendUpdateAfterMillis`	number	Added in v2.1. (Optional) Instructs the player to send a single in-progress POST /timePlayed report after the specified number of milliseconds. The player does not send a report if the total playback time is less than the time specified by this key. The player uses the value from the most current report object to determine when to send a report. It will not resend the report if it already reported the current track. Sonos does not send reports for tracks that play for less than one second (1000 milliseconds), therefore any value under 1000 will be treated as 1000. If you set this value to zero, Sonos sends a report when the track starts. If you omit this value, Sonos does not send an initial report.
`periodicIntervalMillis`	number	Added in v2.1. (Optional) Instructs the player to periodically send in-progress POST /timePlayed reports at the specified interval. The player sends the first report at the specified interval after the first report sent using the `sendUpdateAfterMillis` value. If your server did not set a `sendUpdateAfterMillis` value, the player sends the first periodic report at the specified interval after playback commences. The minimum value is 10 seconds (10000 milliseconds). Any value less than this (except zero) will be considered to be 10000 milliseconds.
`sendPlaybackActions`	Boolean	Added in v2.2. (Optional, default = false) When true, instructs the player to send POST /timePlayed reports to account for actions that pause playback or skip to the next track. If you’ve enabled the `pauseAtEndOfQueue` playback policy, the player sends a report when it reaches the end of the queue.

Scenarios

The following are some scenarios that demonstrate how you can set different report schedules:

sendUpdateAfterMillis	periodicIntervalMillis	Report Schedule
omitted	omitted	Sonos sends one report at track completion.
0	omitted	Sonos sends a report at track start and at completion.
5000	omitted	Sonos sends a report after 5 seconds of playback and at completion.
5000	30000	Sonos sends a report after 5 seconds, periodic reports at 35 seconds, 65 seconds, and every 30 seconds thereafter, and at track completion.
0	30000	Sonos sends a report at track start, periodic reports at 30 seconds, 60 seconds, and every 30 seconds thereafter, and at track completion.
omitted	30000	Sonos sends periodic reports at 30 seconds, 60 seconds, and every 30 seconds thereafter, and at track completion.

Examples

Here is an example response for a DMCA-compliant artist radio station:

{
  "contextVersion": "<version-string-for-this-context>",
  "queueVersion": "<version-string-for-the-queue>",
  "container": {
    "type": "trackList.program",
    "name": "Bruce Springsteen Radio",
    "imageUrl": "http://images.example.com/program_art.jpg",
    "id": {
      "serviceId": "7",
      "objectId": "sta12345",
      "accountId": "user981"
    },
    "service": {
      "name": "Acme"
    },
  },
  "playbackPolicies": {
    "canSkip": true,
    "limitedSkips": true,
    "canSkipToItem": false,
    "canSkipBack": false,
    "canSeek": false,
    "canCrossfade": true,
    "showNNextTracks": 3,
    "showNPreviousTracks": 0
  }
}

Here is an example response for a user’s private playlist:

{
  "contextVersion": "<version-string-for-this-context>",
  "queueVersion": "<version-string-for-the-queue>",
  "container": {
    "type": "playlist",
    "name": "Liked from Radio",
    "id": {
      "serviceId": "8",
      "objectId": "music:user:john.musiclover:playlist:5t33Mtrb6rFBqvgz0U2DQe",
      "accountId": "john.musiclover"
    },
    "service": {
      "name": "Acme2"
    }
  },
  "reports": {
    "sendUpdateAfterMillis": 30000,
    "sendPlaybackActions": true
  },
  "playbackPolicies": {
    "canSkip": true,
    "limitedSkips": false,
    "canSkipToItem": true,
    "canSkipBack": true,
    "canSeek": true,
    "canRepeat": false,
    "canRepeatOne": false,
    "canCrossfade": true,
    "canShuffle": false,
    "showNNextTracks": 10,
    "showNPreviousTracks": 10
  }
}

Error handling

This table describes the expected error codes for GET /context. Your cloud queue server should return these HTTP error codes when there are errors. 4xx errors are player (client) errors. 5xx errors are cloud queue (server) errors.

Error Code	Name	Description
`401`	Unauthorized	The access token has expired or is invalid.
`403`	Forbidden	Reason can be returned in the `X-Rejected-Reason` HTTP header for your cloud queue server, for logging purposes. In v2.1 and higher, the player suspends the associated session and stops playback. In v2.0 and earlier, the player evicts the session. Note: Any instance of this error will be reported as a `CLOUD_STREAM_LIMIT_ERROR` error. However, this is not the only cause for `403` errors.
`404`	Not Found	Player evicts the session.
`503`	Service Unavailable	The player will retry after the time in the `Retry-After` HTTP header.

As of Sonos software version 8.5, players retry GET /context requests when they receive an unexpected response code. Players also retry when they can’t connect to your server or if the connection is closed ungracefully. This change affects all versions of the Cloud Queue API.