Implementation

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>

XML

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();

JS

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();

JS

Check Activation

To check if the plugin is currently activated, run:

wtSmart.extension.youtube.isActivated();

JS

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>

XML

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>

XML

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>

XML

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",
    },
});

JS

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",
            };
        }
    },
});

XML

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",
        };
    },
});

XML

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();

JS

To reactivate, run

window.wts.get("youtube").activate();

JS

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>

XML

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>

XML

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>

XML

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",
    },
};

JS

The mediaParameter can also be written as a string:

window.mapp_youtubeConfig = {
	title: "My title",
	mediaParameter: "mg1=Embedded YouTube Video;ck3=ck3 value",
};

JS

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;
    },
};

JS

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;
    },
};

JS

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",
});

JS

If you have several plugins, separate them with a semicolon:

executePluginFunction: "mapp_youtubeTracking;some_other_plugin",

JS

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();

JS

To reactivate, run

wt.youtube.activate();

JS

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>

XML

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>

XML

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>

XML

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",
    },
};

JS

The mediaParameter can also be written as a string:

window.mapp_youtubeConfig = {
    title: "My title",
    mediaParameter: "mg1=Embedded YouTube Video;ck3=ck3 value",
};

JS

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;
    },
};

JS

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;
    },
};

JS

Zero Configuration Implementation

Limitations

Dynamic YouTube iFrames

Deactivate YouTube Tracking

Check Activation

Optional loading optimization

Advanced configuration

Configuration via attributes

Configuration via JavaScript

Configuration example for Video Analytics

Zero configuration implementation

Limitations

Dynamic YouTube iFrames

Deactivate YouTube tracking

Check Activation

Optional loading optimization

Advanced configuration

Configuration via attributes

Configuration in TI via optional plugin settings

Configuration via JavaScript

Configuration example for Video Analytics

Zero configuration implementation

Limitations

Dynamic YouTube iFrames

Deactivate YouTube tracking

Check Activation

Optional loading optimization

Advanced configuration

Configuration via attributes

Configuration via JavaScript

Configuration example for Video Analytics

Cookie Notice