- 16 Minutes to read
- Print
- DarkLight
Implementation
- 16 Minutes to read
- Print
- DarkLight
How you implement the plugin depends on your current Mapp setup. Please select the relevant tab below.
Youtube plugin Smart Pixel
Zero Configuration Implementation
This is as simple as loading the plugin script, loading Smart pixel, and running the activate () method after the YouTube video(s) are loaded.
<!DOCTYPE html>
<html lang="en">
<head>
<title>Smartpixel Youtube tracking</title>
<script src="/link/to/smart-pixel.min.js"></script>
<script src="/link/to/smart-pixel-youtube.min.js"></script>
</head>
<body>
<script>
wtSmart.init.set({
trackId: "12345678910111213",
trackDomain: "mapp-trackdomain.wt-eu02.net",
});
wtSmart.track();
</script>
<h1>Smartpixel Youtube tracking</h1>
<iframe
width="560"
height="315"
src="https://www.youtube.com/embed/zZZLfd-9shk"
title="YouTube video player"
frameborder="0"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
allowfullscreen
></iframe>
</body>
<script>
wtSmart.extension.youtube.activate();
</script>
</html>
This code allows you to track the media events of a YouTube video. You can have several YouTube videos on your page. The title of the video is used as a mi parameter (video title in Mapp Intelligence).
Limitations
Changing the volume or muting the video does not fire events, so the tracking does not occur immediately. The updated values are in the subsequent request, for example in the next position request.
Videos embedded via the privacy-enhanced mode (from the domain youtube-nocookie.com) will not work, because they are not supported by the YouTube API.
Dynamic YouTube iFrames
If you load a YouTube iFrame dynamically after you ran the activate method, it won't be tracked automatically. You need to inform the plugin that a new element is available by running:
wtSmart.extension.youtube.install();
You can also run the install method after removing a YouTube iFrame element.
Deactivate YouTube Tracking
To deactivate tracking of YouTube videos, run:
wtSmart.extension.youtube.deactivate();
Check Activation
To check if the plugin is currently activated, run:
wtSmart.extension.youtube.isActivated();
Optional loading optimization
If you take a close look at your website, you'll see that the YouTube iFrame reloads as soon as you run the activate() or install() methods. This happens because the plugin has to add the URL query parameter enablejsapi=1 to the YouTube URL. Without that parameter, the media events are not available.
You can avoid reloading by adding this parameter to your YouTube embed code yourself. So instead of:
<iframe
width="560"
height="315"
src="https://www.youtube.com/embed/zZZLfd-9shk"
title="YouTube video player"
frameborder="0"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
allowfullscreen
></iframe>
you embed the video like this on your website:
<iframe
width="560"
height="315"
src="https://www.youtube.com/embed/zZZLfd-9shk?enablejsapi=1"
title="YouTube video player"
frameborder="0"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
allowfullscreen
></iframe>
Advanced configuration
It is possible to configure the plugin further to change the mi parameter (video title), add media categories (mg) and add event parameters (ck) to media requests.
Configuration via attributes
You can set media titles and media categories via attributes. All you have to do is to add data-title or data-categoryX to the iFrame element, where X is the number of the category. So to set a value for media category 7, you add the attribute data-category7.
<iframe
width="560"
height="315"
src="https://www.youtube.com/embed/zZZLfd-9shk"
title="YouTube video player"
frameborder="0"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
allowfullscreen
data-title="My custom media title"
data-category7="My media category 7 value"
></iframe>
Configuration via JavaScript
You can also add a configuration object as an argument to the activate method or you can call the config method to update the configuration. If both attributes and JavaScript configuration are available, the attribute values are used.
Key | Type | Default |
---|---|---|
title | string/function | YouTube title |
categories | object/function | none |
action | object/function | none |
Use strings and objects if you have static data and just one video on your page:
wtSmart.extension.youtube.config({
title: "My title",
categories: {
1: "Embedded YouTube Video",
22: "value of media category 22",
},
action: {
3: "ck3 value",
},
});
Now in the initial media request, the title and category are attached to the video data. Also, every media request will have ck parameters with the values defined in the config. However, most of the time you will want to have more dynamic actions. For example, only during seek events, just when the video is muted, or over a certain position, etc.
If you have several videos on your page, with the static configuration from above, now all your videos would have the title "My title". For that reason, you can define functions that need to return the configuration value, but they receive the YouTube player object and in the case of the actions, the media event name.
Key | Argument |
---|---|
Title | YouTube Player |
Category | YouTube Player |
Action | YouTube Player, media event name |
Here are some of the YouTube player values that might be interesting for you:
Method | Definition |
---|---|
player.getVideoData().video_id | YouTube id |
player.getVideoData().title | YouTube title |
player.getCurrentTime() | current position |
player.getDuration() | duration of the video |
player.getVolume() | current volume |
player.isMuted() | mute state |
You can find more information about the YouTube API here: https://developers.google.com/youtube/iframe_api_reference
The second argument of the action function will be one of the strings: play, pause, seek, position, and end.
Here is an example configuration for a website that has two videos embedded, with customized titles, media category 1 based on the duration, and action parameter if the video was paused later than 10 seconds in:
wtSmart.extension.youtube.activate({
title: function (player) {
switch (player.getVideoData().video_id) {
case "zZZLfd-9shk":
return "Mapp video 1";
case "0Og7oA8DGPQ":
return "Mapp video 2";
}
},
categories: function (player) {
if (player.getDuration() < 20) {
return {
1: "Short videos",
};
} else {
return {
1: "Long videos",
};
}
},
action: function (player, mediaEvent) {
if (mediaEvent === "pause" && player.getCurrentTime() > 10) {
return {
1: "Paused later than 10 seconds",
};
}
},
});
Configuration example for Video Analytics
If you use Video Analytics in Mapp Intelligence, by default you need the following configuration. Media category 1 (mg1) is the title of the video, media category 15 is the thumbnail URL, and the primary media identifier is the video id.
This can easily be accomplished by this configuration code:
wtSmart.extension.youtube.activate({
title: function (player) {
return player.getVideoData().video_id;
},
categories: function (player) {
return {
1: player.getVideoData().title,
15:
"https://img.youtube.com/vi/" +
player.getVideoData().video_id +
"/hqdefault.jpg",
};
},
});
Embedded YouTube Tracking for Tag Integration
Zero configuration implementation
Go to your container in Mapp Tag Integration, and click Add Plugin.
Then pick the Youtube Tracking Plugin.
Click Next.
Assign a rule that permits loading the plugin on all pages with Youtube videos.
Save your container and publish the changes. Make sure that the Mapp Intelligence pixel is loaded.
After the first track request (which most of the time is the page request) the plugin will look for embedded Youtube videos on the page and will track the media events. If that first request happens before the Youtube videos are loaded, you need to run window.wts.get("youtube").install() at a later point in time to make the plugin search for Youtube videos again. This can be accomplished by adding a custom plugin in Tag Integration, or you can run the code right on your website. Just keep in mind that the 'wts' object might not exist for visitors who use ad blockers and this prevents Tag Integration from loading.
You can have several YouTube videos on your page. The title of the video is used as the mi parameter (video title in Mapp Intelligence).
Limitations
Changing the volume or muting the video does not fire events, so tracking does not occur immediately. The updated values are in the subsequent request, for example in the next position request.
Videos that are embedded via the privacy-enhanced mode (from the domain youtube-nocookie.com) will not work, because they are not supported by the YouTube API.
Dynamic YouTube iFrames
If you load a YouTube iFrame dynamically after your first request or after running window.wts.get("youtube").install(), it will not be tracked automatically. You need to inform the plugin that a new element is available by running window.wts.get("youtube").install() again. You can also run the install method after you removed a YouTube iFrame element.
Deactivate YouTube tracking
To deactivate tracking of YouTube videos, run
window.wts.get("youtube").deactivate();
To reactivate, run
window.wts.get("youtube").activate();
Check Activation
You can find the info if the plugin is currently activated in the property window.wts.get("youtube").isActivated. This property will be true or false.
Optional loading optimization
If you take a close look at your website, you'll see that the YouTube iFrame reloads as your first track request occurs or after running the window.wts.get("youtube").install() method. This happens because the plugin has to add the URL query parameter enablejsapi=1 to the YouTube URL. Without that parameter, the media events are not available.
You can avoid reloading by adding this parameter to your YouTube embed code yourself. So instead of
<iframe
width="560"
height="315"
src="https://www.youtube.com/embed/zZZLfd-9shk"
title="YouTube video player"
frameborder="0"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
allowfullscreen
></iframe>
you embed the video like this on your website:
<iframe
width="560"
height="315"
src="https://www.youtube.com/embed/zZZLfd-9shk?enablejsapi=1"
title="YouTube video player"
frameborder="0"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
allowfullscreen
></iframe>
Advanced configuration
It is possible to configure the plugin further to change the mi parameter (video title), add media categories (mg) and add event (ck), session (cs), and e-commerce (cb) parameters to media requests.
Configuration via attributes
You can set configuration via attributes. All you have to do is to add data-title or data-media-parameter to the iFrame element:
<iframe
width="560"
height="315"
src="https://www.youtube.com/embed/zZZLfd-9shk"
title="YouTube video player"
frameborder="0"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
allowfullscreen
data-title="My custom media title"
data-media-parameter="mg1=test media category 1;cs3=some session parameter value"
></iframe>
Configuration in TI via optional plugin settings
If you go to the YouTube plugin settings in Tag Integration, you can open the optional settings. Here you can set static values for the title of the video, and media parameter. Note that all videos will have that configuration, so only use this if you track a single video. For a more dynamic configuration, see the next section.
Field | Example |
---|---|
title | My awesome YouTube video |
mediaParameter | mg1=test media category 1;cs3=some session parameter value |
Configuration via JavaScript
You can also configure the plugin via JavaScript by changing the global object window.mapp_youtubeConfig. You can use Custom Plugins in Tag Integration to do so. This object will be read right before every media request.
However, it will be ignored if a corresponding attribute is set on the element (see above).
Key | Type | Default value |
---|---|---|
title | string/function | YouTube title |
mediaParameter | string/object/function | none |
You use strings and objects if you have static data and just one video on your page:
window.mapp_youtubeConfig = {
title: "My title",
mediaParameter: {
mg1: "Embedded YouTube Video",
mg22: "value of media category 22",
ck3: "ck3 value",
},
};
The mediaParameter can also be written as a string:
window.mapp_youtubeConfig = {
title: "My title",
mediaParameter: "mg1=Embedded YouTube Video;ck3=ck3 value",
};
With this in place, every media request will have the parameters with the values defined in the configuration.
However, most of the time you want to have dynamic actions or e-commerce parameters. For example only during seek events, just when the video is muted, or over a certain position, etc. If you have several videos on your page with the static configuration from above, now all your videos would have the title "My title". For that reason, you can define functions that need to return the configuration value, but receive the YouTube player object and, in the case of the mediaParameter, the media event name.
Key | Arguments |
---|---|
title | YouTube player |
mediaParameter | YouTube player, Media event name |
Here are some of the YouTube player values that might interest you:
Method | Info |
---|---|
player.getVideoData().video_id | YouTube id |
player.getVideoData().title | YouTube title |
player.getCurrentTime() | current position |
player.getDuration() | duration of the video |
player.getVolume() | current volume |
player.isMuted() | mute state |
You can find more information about the YouTube API here: https://developers.google.com/youtube/iframe_api_reference
The second argument of the mediaParameter function will be one of the strings; play, pause, seek, pos, or eof.
Here is an example configuration for a website that has two videos embedded with customized titles, media category 1 based on the duration, and action parameter if the video was paused later than 10 seconds in:
window.mapp_youtubeConfig = {
title: function (player) {
switch (player.getVideoData().video_id) {
case "zZZLfd-9shk":
return "Mapp video 1";
case "0Og7oA8DGPQ":
return "Mapp video 2";
}
},
mediaParameter: function (player, mediaEvent) {
var mediaParameter = {};
mediaParameter.mg1 =
player.getDuration() < 20 ? "Short videos" : "Long videos";
if (mediaEvent === "pause" && player.getCurrentTime() > 10) {
mediaParameter.ck1 = "Paused later than 10 seconds";
}
return mediaParameter;
},
};
Configuration example for Video Analytics
If you use Video Analytics in Mapp Intelligence, by default you need the following configuration: media category 1 (mg1) is the title of the video, media category 15 is the thumbnail URL and the primary media identifier is the video id.
This can easily be accomplished by this configuration code:
window.mapp_youtubeConfig = {
title: function (player) {
return player.getVideoData().video_id;
},
mediaParameter: function (player, mediaEvent) {
var mediaParameter = {};
mediaParameter.mg1 = player.getVideoData().title;
mediaParameter.mg15 =
"https://img.youtube.com/vi/" +
player.getVideoData().video_id +
"/hqdefault.jpg";
return mediaParameter;
},
};
YouTube Plugin V4
Zero configuration implementation
You load the plugin by embedding the pixel-youtubetracking.min.js file as early as possible on your page. The earlier you load the script, the sooner the Youtube Embed API is ready, which is needed to track media events. After that, you need to load Pixel V4, and add mapp_youtubeTracking to the execute Plugin Function property:
var wt = new webtrekkV3({
trackId: "123123123123123",
trackDomain: "your.track.domain",
mediaCode: "wt_mc",
cookie: "1",
safetag: {},
executePluginFunction: "mapp_youtubeTracking",
});
If you have several plugins, separate them with a semicolon:
executePluginFunction: "mapp_youtubeTracking;some_other_plugin",
After the first track request (which most of the time is the page request) the plugin will look for embedded YouTube videos on the page and will track the media events. If that first request happens before the YouTube videos are loaded, you can run wt.youtube.install() at a later time to make the plugin search for YouTube videos again.
You can have several YouTube videos on your page. The title of the video is used as mi parameter (video title in Mapp Intelligence).
Limitations
Changing the volume or muting the video does not fire events, so the tracking does not occur immediately, but the updated values are in the subsequent request, for example in the next position request.
Videos that are embedded via the privacy-enhanced mode (from the domain youtube-nocookie.com) will not work, because they are not supported by the YouTube API.
Dynamic YouTube iFrames
If you load a YouTube iFrame dynamically after your first request or after running wt.youtube.install(), it will not be tracked automatically. You need to inform the plugin that a new element is available by running wt.youtube.install() again. You can also run the install method after you removed a YouTube iFrame element.
Deactivate YouTube tracking
To deactivate tracking of YouTube videos, run
wt.youtube.deactivate();
To reactivate, run
wt.youtube.activate();
Check Activation
You can find the info if the plugin is currently activated in the property wt.youtube.isActivated. This property will be true or false.
Optional loading optimization
If you take a close look at your website, you'll see that the YouTube iFrame reloads as your first track request occurs or after running the wt.youtube.install() method. This happens because the plugin has to add the URL query parameter enablejsapi=1 to the YouTube URL. Without that parameter, the media events are not available. You can avoid reloading by adding this parameter to your YouTube embed code yourself. So instead of
<iframe
width="560"
height="315"
src="https://www.youtube.com/embed/zZZLfd-9shk"
title="YouTube video player"
frameborder="0"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
allowfullscreen
></iframe>
you embed the video like this on your website:
<iframe
width="560"
height="315"
src="https://www.youtube.com/embed/zZZLfd-9shk?enablejsapi=1"
title="YouTube video player"
frameborder="0"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
allowfullscreen
></iframe>
Advanced configuration
It is possible to configure the plugin further to change the mi parameter (video title), add media categories (mg) and add event (ck), session (cs), and e-commerce (cb) parameters to media requests.
Configuration via attributes
You can set configuration via attributes. All you have to do is to add `data-title` or `data-media-parameter` to the iFrame element:
<iframe
width="560"
height="315"
src="https://www.youtube.com/embed/zZZLfd-9shk"
title="YouTube video player"
frameborder="0"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
allowfullscreen
data-title="My custom media title"
data-media-parameter="mg1=test media category 1;cs3=some session parameter value"
></iframe>
Configuration via JavaScript
You can also configure the plugin via Javascript by changing the global object window.mapp_youtubeConfig. This object will be read right before every media request. However, it will be ignored if a corresponding attribute is set on the element (see above).
Key | Type | Default value |
---|---|---|
title | string/function | YouTube title |
mediaParameter | string/object / function | none |
You use strings and objects if you have static data and just one video on your page:
window.mapp_youtubeConfig = {
title: "My title",
mediaParameter: {
mg1: "Embedded YouTube Video",
mg22: "value of media category 22",
cK3: "ck3 value",
},
};
The mediaParameter can also be written as a string:
window.mapp_youtubeConfig = {
title: "My title",
mediaParameter: "mg1=Embedded YouTube Video;ck3=ck3 value",
};
With this in place, every media request will have the parameters with the values defined in the config. However, most of the time you will want to have actions or e-commerce parameters to be more dynamic, for example only during seek events, or just when the video is muted or over a certain position etc. Also, if you have several videos on your page, with the static configuration from above, now all your videos would have the title "My title". For that reason, you can define functions, that need to return the configuration value, but they receive the YouTube player object and in the case of the mediaParameter, the media event name.
Key | Arguments |
---|---|
title | YouTube player |
mediaParameter | YouTube player, Media event name |
Here are some of the YouTube player values that might be interesting for you:
Method | Info |
---|---|
player.getVideoData().video_id | YouTube id |
player.getVideoData().title | YouTube title |
player.getCurrentTime() | current position |
player.getDuration() | duration of the video |
player.getVolume() | current volume |
player.isMuted() | mute state |
You can find more information about the YouTube API here: https://developers.google.com/youtube/iframe_api_reference
The second argument of the mediaParameter function will be one of the strings play, pause, seek, pos, or eof.
Here is an example configuration for a website that has two videos embedded, with customized titles, media category 1 based on the duration, and action parameter if the video was paused later than 10 seconds in:
window.mapp_youtubeConfig = {
title: function (player) {
switch (player.getVideoData().video_id) {
case "zZZLfd-9shk":
return "Mapp video 1";
case "0Og7oA8DGPQ":
return "Mapp video 2";
}
},
mediaParameter: function (player, mediaEvent) {
var mediaParameter = {};
mediaParameter.mg1 =
player.getDuration() < 20 ? "Short videos" : "Long videos";
if (mediaEvent === "pause" && player.getCurrentTime() > 10) {
mediaParameter.ck1 = "Paused later than 10 seconds";
}
return mediaParameter;
},
};
Configuration example for Video Analytics
If you use Video Analytics in Mapp Intelligence, by default you need the following configuration: media category 1 (mg1) is the title of the video, media category 15 is the thumbnail URL and the primary media identifier is the video id.
This can be accomplished with this configuration code:
window.mapp_youtubeConfig = {
title: function (player) {
return player.getVideoData().video_id;
},
mediaParameter: function (player, mediaEvent) {
var mediaParameter = {};
mediaParameter.mg1 = player.getVideoData().title;
mediaParameter.mg15 =
"https://img.youtube.com/vi/" +
player.getVideoData().video_id +
"/hqdefault.jpg";
return mediaParameter;
},
};