Intent To Implement: Video Analytics #9902
Description
Summary
The goal is for amp-video and also other video players in AMP to issue events for major states to be reported through amp-analytics.
#1654 and #2802 have some background on the requirements.
Example
<amp-analytics>
<script type="application/json">
{
"requests": {
"event": "https://foo.com/va?vid=${videoId}&sid=${sessionId}&pt={playedTotal}&ap={autoplay}"
},
"triggers": {
"videoSession": {
"on": "video-session",
"selector": "amp-video",
"request": "event",
"spec": {
"end-session-when-invisible": true,
"exclude-autoplay": false
}
}
}
}
}
</script>
</amp-analytics>
Common Variables
All Video Triggers will provide the following variables:
| Var | Type | Description |
|---|---|---|
| ${videoid} | String | Id of the video element |
| ${videoDuration} | Number | Total duration of the video in seconds |
| ${muted} | Boolean | Whether video was muted at the time of trigger |
| ${paused} | Boolean | Whether video was paused at the time of trigger |
| ${ended} | Boolean | Whether video had ended at the time of trigger |
| ${currentTime} | Number | Current playback time in seconds at the time of trigger |
| ${fullscreen} | Boolean | Whether video was in fullscreen at the time of trigger |
| ${autoplay} | Boolean | Whether video was in autoplay mode at the time of trigger. NOTE: This can be different than presence of autoplay attribute since 1- platform/user may have disable autoplay, 2- User may have, interacted with video and therefore exiting the autoplay mode by tapping,the video. |
| ${width} | Number | Width of video in PX |
| ${height} | Number | Height of video in PX |
??QUESTION??: Should these be specific to video triggers or also be exposed as Url substitutions (to be used in other triggers) or both? Do we want devs to use these values in a Timer trigger for instance?
Triggers
video-play (P0)
Issued when video is played (either autoplay or explicit manual play). ${autoplay} variable
can be used to differentiate.
video-pause (P0)
Issued when video is paused (either autoplay pause or explicit manual pause). {autoplay} variable
can be used to differentiate.
video-ended (P0)
Issued when video ends.
video-session (P0)
A video session starts when a video is played and ends when video pauses, ends
or goes out of the view (if configured in the spec). Autoplaying videos can be optionally
removed from this reporting. Seeking or buffering does not end a session.
QUESTION: How about unload/document swipes in viewer? We need to end session and ping analytics. Document swipes in viewer should be fine, but how about page unload? Do we/can we use onbeforeunload to do this?
Spec
| Key | Value | Description |
|---|---|---|
| "end-session-when-invisible" | Boolean (false default) | Whether video going out of viewport should consider an end to the session even if it is still playing. |
| "exclude-autoplay" | Boolean (false default) | Whether autoplaying videos should be excluded from this trigger. |
Additional variables
| Var | Type | Description |
|---|---|---|
| ${playedRangesJson} | String | Array of {start, end} objects for each continuous playback segment as a JSON string. Overlapping ranges are possible if user replays a section. Every scrub will generate a new entry in this array. |
| ${scrubRangesJson} | String | Array of {start, end} objects for each scrub as a JSON string. Overlapping ranges are possible. |
| ${sessionid} | String | A unique id for the session in the format if {videoid}-{auto-incrementing-session-number} (e.g. myvideo-1) |
| ${playedTotal} | Number | Total playing time for the session in seconds, includes overlapping watch segments. |
video-seconds-played (P0 - unless there is immediate interest)
Issued every time x seconds of video is played. Overlapping plays are still considered as play time.
This is essentially a timer trigger that is paused when video is paused.
Spec
| Key | Value | Description |
|---|---|---|
| "Interval" | Number (5 default) | How many seconds of playtime needs to pass before this fires. |
video-fullscreen-enter (P1)
Issued when video enters fullscreen mode.
video-fullscreen-exit (P1)
Issued when video exists fullscreen mode.
video-autoplay-interacted (P1)
Issued when user interacts with an autoplaying video.
NOTE: The following triggers are low-priority P2 features assuming video-session trigger handles most of the common use-cases.
video-scrub (P2 - unless there is immediate interest)
Issued when user is seeking within the video.
Additional variables
| Var | Type | Description |
|---|---|---|
| ${scrubStart} | Number | Start time of the scrub in seconds |
| ${scrubEnd} | String | End time of the scrub in seconds |
video-percent-played (P2 - unless there is immediate interest)
Issued every time x% of total video duration is watched. playedTimeRanges is used
to calculated percentage of total duration watched.
Overlapping play ranges are only counted once for calculation.
| Key | Value | Description |
|---|---|---|
| "Interval" | Number (25% default) | What percentage of playtime needs to pass before this fires. |
How about other video players?
Video analytics will be implemented based on the video-interface rather than individual elements.
video-interface will be extended to include events that we would need to implement analytics however:
- Not every player implements
video-interface(8 do) - Not every implementation will initially include the new events needed for analytics, as video players expose the needed events, analytics would be enabled for them. Initial focus would be on
amp-videofollowed byamp-ima-video,amp-iframe-videoand maybeamp-youtube.
Many 3P players provide their own separate video analytics anyway making this lower priority.
amp-ima-video
@shawnbuso for insight. Does IMA SDK provide any sort of analytics for the
ads and/or video itself?
If not:
- We need
amp-ima-videoto support the same analytics asamp-video - Determine what Ad related triggers we need to add in addition. Would adding
two newvideo-ad-startandvideo-ad-endtriggers suffice?
amp-iframe-video
This component does not exist yet, but scheduled. As long as the embedded video inside
the amp-iframe-video fully implements the video-interface, all analytics triggers should work.
amp-x-player
As discussed, lower priority since many have their own analytics and adoption of the video-interface and extended events needed for analytics is usually slow.