Questions about UsageReportingClient GetUserDetailedUsage (Date: 2018-08-29)
Original Post by Erik Steinebach, August 29, 2018 at 3:08 PM
A couple of questions about this method in the API:
Is this data fixed, so if a user watches a video one "DetailedUsageResponseItem" is created and if the user watches the video again a new "DetailedUsageResponseItem" is added and 2 items will be returned. Or could the original "DetailedUsageResponseItem" be updated after I have received it? Because in that case I would have to always regenerate all the data for a user
The Time field is the time the user started watching the video?
Is there a maximum amount of response items and pages that will be returned? And until a maximum amount of time (will I always get everything for a user with infinite history)?
Mark Brewsala, Moderator, October 4, 2018 at 7:12 PM
Each DetailedUsageResponseItem describes some part of a view by the requested user. In this scenario then, at least 2 items would be returned after the second view of the same video by the same user. I say at least because even seeks, pauses, and playback speed changes within a single view will result in one DetailedUsageResponseItem for each such event.
Understanding this, we see that the Time field is the clock time at which that particular view segment began. The StartPosition field, in contrast, is the position in the video's timeline where that view segment started, where 0 represents the beginning of the video.
All view information for the specified viewer can be returned, so in principle there is no upper limit to the number of pages that could be involved, and they can each be requested in turn. Each page contains 25 DetailedUsageResponseItems by default, but different page sizes can be requested.
There is no way to limit the result set by explicit date ranges. But the paged result set is returned in chronological order based on when the view segments happened, so the result set can be indirectly time-limited by choosing the page sizes and numbers to ask for.
Erik Steinebach, October 16, 2018 at 9:28 PM
Thank you for your response.
We have been progressing with this information to develop a way to get all the data. But I am running into another somewhat strange situation where for a specific user and video we have views with the same "Time" field, but different StartPosition and Duration. For example:
ViewedDate StartPosition EndPosition Duration
2016-08-18 18:14:38.507 366 370 4
2016-08-18 18:14:38.507 256 270 14
What does this mean?
I am trying to calculate the total time the user has watched videos. Do I sum all these durations? Or should I just select a single one?
Mark Brewsala, Moderator, October 17, 2018 at 2:44 PM
The right thing to do in such cases is to sum the durations. Both records in the example you cited represent distinct playback events.
The Time that's recorded and displayed upon API request is the time at which the server received the video playback telemetry from the viewer client. For performance sake our telemetry clients batch telemetry updates to about one or two per minute. A consequence of this is that the precision of the Time field as reported by this API is in reality down to about a 1-minute granularity.
Short view periods like those in the example you cited are the result of rapid viewer gesture (pause, seek, playback speech change, etc.) that will often be batched together in this way and therefore report the same (server) Time.