reportPlaySeconds
This endpoint is deprecated
See Add reporting for details.
Sonos uses reportPlaySeconds to report detailed playback reporting from a Sonos player. You must enable the "Playback event logging during track play" capability to receive these reports from players. See Add capabilities for details.
Request parameters
| Name | Type | Description |
|---|---|---|
id | string(128) | The ID of the played track. |
seconds | int | The total number of seconds for which the track played. Due to seeking, this may be longer than the total duration of the track. While in a paused state, time does not count toward the number of played seconds. Tracks playing less than one whole second are not reported. |
offsetMillis | int | (Optional) The playhead position, in milliseconds for the track. This is only reported if the track or the container that the track is in has a canResume value of true. See Save & resume playback for details. |
contextId | string | Sonos provides an ID to add context about where the track was playing from. For example, if a user browsed to an album and queued the album container, the contextId would be the album container ID. If they played a track, it would be the track ID. Supported sources include:- program radio - single track - album - a playlist from your service - artist - stream - audiobookThis is empty if a user plays a Sonos playlist. Select the "Add play context to reporting" capability to enable. See Add capabilities for details. |
Response
| Name | Type | Description |
|---|---|---|
interval | string(128) | The length of time in seconds to poll for this report. Set to a minimum of 10 seconds, or set to "0" to stop the player from sending reportPlaySeconds events for the current song (the player will only send the initial report). The default value, 60 seconds, will be used if you do not specify the interval. |
Sonos first sends this report after at least one second of audio
This method reports the cumulative number of seconds played of a song at specified intervals. The player first sends this notification when a song starts and has played at least one second of audio (a 'seconds' value of 1). Thereafter, a player sends this notification after a specified interval (by default, after approximately 60 seconds of playback). An interval of 0 signals the player to stop sending reportPlaySeconds events for the current track.
Sonos sends subsequent reports at approximate intervals
The interval is approximate because reportPlaySeconds is not reported synchronously. The notification is added to a timed job queue and reported when that job comes up. The time accumulates until the player sends the report to your music service. For example, if your service accepts the default interval of 60 seconds, you will receive a reportPlaySeconds notification after 1 second of the track has played, then another one after a minimum of 60 seconds has passed. However, the job could be delayed. For example, it could sit in the queue for an extra 2 seconds. Therefore, when it is sent, the value would be 63 seconds. The initial 1 second, plus a 2 second delay, plus the 60 second interval. Note that even though the report was delayed, it will still accurately report the amount of time that the Sonos player played your audio.
Sample use case
You may want to use this report to keep track of the number of seconds that a song has been played, for licensing purposes. For example, if your service has to know if a song has played for 30 seconds, you might send an interval of 29 after receiving your initial reportPlaySeconds notification after 1 second. Then, after receiving a notification after about 30 seconds of playback, you might send an interval of 0 to not receive any more notifications, as the song has already progressed past your threshold of 30 seconds.
Sample request
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<reportPlaySeconds xmlns="http://www.sonos.com/Services/1.1">
<id>t10001</id>
<seconds>360</seconds>
<contextId>album:2343</contextId>
</reportPlaySeconds>
</soap:Body>
</soap:Envelope>
Sample response
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<reportPlaySecondsResponse xmlns="http://www.sonos.com/Services/1.1">
<reportPlaySecondsResult>
<interval>60</interval>
</reportPlaySecondsResult>
</reportPlaySecondsResponse>
</soap:Body>
</soap:Envelope>
Updated over 1 year ago