Statistics Pingbacks

Statistics are measured through pingbacks. This allows us to measure unique views and player engagement (e.g. at what point in the video does a viewer lose interest and close the video?). The only way to reliably measure these metrics, is through client-side integration into the video player, in our case using HTTP pingback requests.

Add StreamOne Pingbacks to your applications to allow us to measure views per video-item per application (video on demand only; livestreams are measured serverside).

There are multiple pingback implementation levels that can be supported. In order to correctly implement a category, all pingbacks from that category need to be supported.

Note

Pingbacks have already been implemented in the StreamOne embed frame.

General

We retrieve a dot.gif image from the progressive video hostname and add url-parameters to it:

http://<hostname>/ping/dot.gif

In order to prevent caching, the timestamp (in milliseconds!) needs to be added as url-parameter:

?ts=1397044124557

The item ID needs to be transmitted as well, in the following form:

&item=s1iTEmiD251a

In all cases, the video progress (in percents, as integer 0-100) needs to be submitted. Ad progress is never submitted (only main video progress), so pingbacks must never take place during ad playback. The progress is sent using the progress parameter:

&progress=0

In order to perform a by-app measurement, the app’s user agent should be modified so that it contains the Vendor name, App name and Version, for example: CompanyName/AppName 2.3.

If modifying the HTTP User-Agent is not possible or desirable, adding the (urlescaped) ua-parameter will overwrite the HTTP User-Agent. Please note: The User-Agent requesting the content itself (whether it be progressively or using HLS) should be the same as the User-Agent used to send pingbacks:

&ua=CompanyName/AppName%202.3

Also, the implementation level will need to be added if you implement Level 2 or higher (we need this information to correctly calculate engagement information), parameter name is “il”:

&il=2

(if not included, il=1 will be assumed and information other than firstplay/initialized will not be parsed)

It is important that you never send duplicate pingbacks without any reason, because this will make statistics less precise. A duplicate pingback is a pingback with the same pingback name and progress (e.g. sending &event=play&progress=40 twice directly after each other for no functional reason).

Implementation Level 1: basic statistics

This category measures the unique number of plays of a video (no patterns, no completes, just plays). There are only two pingbacks in the level. Progress must always be 0 here.

In Implementation Level 1, it is possible to send both initialized and firstplay pingbacks, or just send the firstplay pingback.

Please note: if you only implement Level 1 for some clients/players and Level 1+2 for other players, it may not be possible to accurately determine viewer engagement;

Pingback “initialized”

This pingback must fire when the videoplayer is loaded, as soon as the user can click play to start the video.

In order to send this event, you only need to send us one extra url-parameter:

&event=initialized

Pingback “firstplay”

This pingback must only fire if the video actually starts. If there is a preroll advertisement, the pingback must fire if the preroll is finished, when the main video starts.

If the user completes playback and restarts the same video, this event must not be re-sent! However, if the user closes the video (closes the page or closes the video view in an app), and then loads the video again (triggering a new initialized pingback), a new firstplay pingback must be fired.

In order to send firstplays to us, only one extra url-parameter is required:

&event=firstplay

Implementation Level 2: hotspot-tracking

This category measures viewing patterns and user engagement: when does a user close the video, to what parts of a video do users seek?

Please note: All Level 1 pingbacks must also be sent if you use Level 2 pingbacks. Level 2 extends Level 1. Level 2 pingbacks always require the addition of the extra &il=2 parameter, even the firstplays and initialized events!

Pingback “play”

If a user starts playing (after a stop) on a specific part of the video, this pingback must be sent. Please do not confuse play/stop with pause/resume.

A possible use-case for play is when starting at e.g. 25% of the video (when using chapters). If you need to preload content in order to know to which chunk/position to seek, please be sure not to send (first)play&progress=0 but only send the progress at which the player actually started!

Pingback “update”

During playback, every 10 percent of the video, an update event must be sent. This excludes the 0% and 100% marks (these should never be sent). The following percentages must be sent: 10, 20, 30, 40, 50, 60, 70, 80, 90.

Pingback “seekfrom”

If a user seeks during a paused/stopped state, no pingbacks must be sent while seeking. If a user seeks during(!) playback, two pingbacks are sent. The first one is seekfrom, containing the progress-position FROM which is being searched, for example:

&event=seekfrom&progress=35

Please note that no play/update/stop events may be sent when seeking!

Pingback “seekto”

If a user seeks during a paused/stopped state, no pingbacks must be sent while seeking. If a user seeks during(!) playback, two pingbacks are sent. The second one is seekto, containing the progress-position to which is being searched (which can of course both be higher or lower than the seekfrom pingback), for example:

&event=seekto&progress=25

Please note that no play/update/stop events may be sent when seeking!

Pingback: “stop”

If a user stops the video or minimizes/closes the app from a playing state, a stop pingback must be sent, containing the current progress. If the video completes, a stop pingback must be sent as well (containing a progress=100).

Pingback “pause”

If a user pauses the video, this event must be sent, including the progress.

Pingback “resume”

If a user resumes a paused video, this event must be sent, including the progress.

Examples

Player is loaded (Level 1 implementation example without &il parameter):

dot.gif?item=X&ts=Y&progress=0&event=initialized

Player is started for the first time (if a preroll is active, these are sent AFTER the preroll finishes – Level 2 implementation examples below, with &il=2 example):

dot.gif?item=X&ts=Y&il=2&progress=0&event=firstplay
dot.gif?item=X&ts=Y&il=2&progress=0&event=play

A checkpoint (at 10%, 20%, ..., 90%) has been reached, e.g. at 30%:

dot.gif?item=X&ts=Y&il=2&progress=30&event=update

Video is being paused, e.g. at 42%:

dot.gif?item=X&ts=Y&il=2&progress=42&event=pause

A paused video is resumed, e.g. 42%:

dot.gif?item=X&ts=Y&il=2&progress=42&event=resume

A user seeks in a video, e.g. from 42% to 74%:

dot.gif?item=X&ts=Y&il=2&progress=42&event=seekfrom
dot.gif?item=X&ts=Y&il=2&progress=74&event=seekto

A user paused the video, then seeks from 42% to 37%, then resumes:

dot.gif?item=X&ts=Y&il=2&progress=42&event=pause
<no event was sent during the seek from 42 to 37>
dot.gif?item=X&ts=Y&il=2&progress=37&event=resume

Video finishes playing (video completes):

dot.gif?item=X&ts=Y&il=2&progress=100&event=stop

User closes video (e.g. closes containing website or closes the video-view in the app) while it is playing at 42%:

dot.gif?item=X&ts=Y&il=2&progress=42&event=stop

User closes video (e.g. closes containing website or closes the video-view in the app) while it is paused at 42%:

<no event is sent because state is not playing>