Snowplow Media Tracking
This plugin will allow the tracking of an embedded YouTube IFrame.
Download
| Download from GitHub Releases (Recommended) | Github Releases (plugins.umd.zip) |
| Available on jsDelivr | jsDelivr (latest) |
| Available on unpkg | unpkg (latest) |
Quick Start
To start tracking a YouTube video with default settings, use the snippet below after setting up your tracker:
index.html
<html>
<head>
<title>Snowplow YouTube Tracking Example</title>
<script src="main.js"></script>
</head>
<body>
<iframe
id="example-id"
src="https://www.youtube.com/embed/zSM4ZyVe8xs"
></iframe>
</body>
</html>Code language: HTML, XML (xml)main.js
window.snowplow(
"addPlugin",
"https://cdn.jsdelivr.net/npm/@snowplow/browser-plugin-youtube-tracking@latest/dist/index.umd.min.js",
["snowplowYouTubeTracking", "YouTubeTrackingPlugin"]
);
window.snowplow("enableYouTubeTracking", {
id: "example-id",
});Code language: JavaScript (javascript)The enableYouTubeTracking function
The enableYouTubeTracking function takes the form:
window.snowplow("enableYouTubeTracking", { id, options?: { label?, captureEvents?, percentBoundaries?, updateRate? } })Code language: JavaScript (javascript)| Parameter | Type | Default | Description | Required |
|---|---|---|---|---|
id | string | – | The HTML id attribute of the media element | Yes |
options.label | string | – | An identifiable custom label sent with the event | No |
options.captureEvents | string[] | ["DefaultEvents"] | The events or Event Group to capture. For a full list of events and groups, check the section below | No |
options.boundaries | number[] | [10, 25, 50, 75] | The progress percentages to fire an event at (valid values 1 – 99 inclusive) [1] | No |
options.updateRate | number | 250 | The rate at which seek and volumechange events can occur [2] | No |
Below is an example of the full enableYouTubeTracking function:
window.snowplow('enableYouTubeTracking', {
id: "example-video",
options: {
label: "My Custom Video Label",
captureEvents: ["play", "pause", "ended"],
boundaries: [20, 80],
updateRate: 200,
}
})Code language: JavaScript (javascript)Usage
For this plugin to find your media element, your IFrame must be given the id that is passed into enableYouTubeTracking:
index.html
<iframe
id="example-id"
src="https://www.youtube.com/embed/zSM4ZyVe8xs"
></iframe>Code language: HTML, XML (xml)main.js
window.snowplow('enableYouTubeTracking', {
id: "example-id"
})Code language: JavaScript (javascript)Events
Capturable Events
Below is a table of all the events that can be used in options.captureEvents
| Name | Fire Condition |
|---|---|
| play | The video is played |
| pause | The video is paused |
| seek | On seek |
| volumechange | Volume has changed |
| ended | When playback stops at the end of the video |
| error | An error occurs in the player |
| percentprogress | When a percentage boundary set in options.boundaries is reached |
| playbackratechange | Playback rate has changed |
| playbackqualitychange | Playback quality has changed |
Event Groups
You can also use a pre-made event group in options.captureEvents:
| Name | Events |
|---|---|
DefaultEvents | ["play", "pause", "seek", "volumechange", "ended", "percentprogress", "playbackratechange", "playbackqualitychange"] |
AllEvents | Every event listed in Capturable Events |
It is possible to extend an event group with any event in the Events table above. This could be useful if you want, for example, all the events contained in the “DefaultEvents” group, along with the “error” event. This is expressed in the following way:
window.snowplow('enableYouTubeTracking', {
id: "example-video",
options: {
captureEvents: ["DefaultEvents", "error"],
}
})Code language: JavaScript (javascript)Schemas and Example Data
Three schemas are used with this plugin:
An unstructured event with identifying information
{
"type": "play",
"label": "Identifying Label"
}Code language: JSON / JSON with Comments (json)Snowplow platform-agnostic media context
{
"currentTime": 12.32,
"duration": 20,
"ended": false,
"loop": false,
"muted": true,
"paused": false,
"playbackRate": 1,
"volume": 100
}Code language: JSON / JSON with Comments (json)YouTube player specific context
{
"autoPlay": false,
"avaliablePlaybackRates": [
0.25, 0.5, 0.75, 1, 1.25, 1.5, 1.75, 2
],
"buffering": false,
"controls": true,
"cued": false,
"loaded": 17,
"playbackQuality": "hd1080",
"playerId": "youtube",
"unstarted": false,
"url": "https://www.youtube.com/watch?v=zSM4ZyVe8xs",
"yaw": 0,
"pitch": 0,
"roll": 0,
"fov": 100.00004285756798,
"avaliableQualityLevels": [
"hd2160",
"hd1440",
"hd1080",
"hd720",
"large",
"medium",
"small",
"tiny",
"auto"
]
}Code language: JSON / JSON with Comments (json)- To track when a video ends, use the “ended” event.
2. seek and volumechange use setInterval to poll the player every n ms. You are able to adjust the poll rate, however, lower values may cause performance issues.
