YouTube Video Tracking Tag Plugin

The YouTube Iframe Player API allows you to embed a video player on your website and control it using JavaScript. The API creates DOM events that Oracle Infinity's YouTube video tracking plugin can use to collect tracking data.

Note: For more details about this implementation, contact your Oracle Infinity solutions consultant.

Requirements

For the YouTube video tracking plugin to work properly:

It must be loaded before the YouTube video player loads.
It must be loaded before other Oracle Infinity code loads.

You should include the following script in the <head> of your web page. It is used to synchronously load the YouTube iframe player code.

<script>
var tag = document.createElement('script');
tag.src = "//www.youtube.com/iframe_api";
var firstScriptTag = document.getElementsByTagName('script')[0];
firstScriptTag.parentNode.insertBefore(tag, firstScriptTag);
</script>

Enable tracking calls from within the YouTube iframe player by adding the enablejsapi=1 option to the query string of the video URL. For example, src="//www.youtube.com/embed/NzbYTJAR0Ac?enablejsapi=1"
To protect against malicious third-party JavaScript being injected into your page and hijacking control of your YouTube iframe player, include the origin parameter to the URL, including http:// or https:// and full domain of your host page as the parameter value.

Note: For more details about this implementation, contact your Oracle Infinity solutions consultant.

Parameters

The YouTube video tracking plugin can send the following Oracle Infinity parameters:

Parameter	Name	Description
`wt.clip_ct`	Video content type	`wt.clip_ct` indicates the video's content type, such as MOV.
`wt.clip_duration`	Duration in seconds	`wt.clip_duration` indicates the video duration in seconds.
`wt.clip_duration_min`	Duration in minutes	`wt.clip_duration_min` indicates the video duration in minutes.
`wt.clip_duration_n`	Duration based on range	`wt.clip_duration_n` indicates the range of the video duration in seconds.
`wt.clip_ev`	Media event identifier	`wt.clip_ev` identifies the type of media-related event that has occurred, such as `v` for a view event.
`wt.clip_id`	Video identifier	`wt.clip_id` indicates the unique ID of the video asset.
`wt.clip_mins`	Playhead in minutes	`wt.clip_mins` indicates the video's playhead position in minutes.
`wt.clip_mode`	Mode type	`wt.clip_mode` identifies the mode type of video, such as fixed, streaming, FullScreenOn, or FullScreenOff.
`wt.clip_n`	Video name	`wt.clip_n` identifies the name of the video that was accessed.
`wt.clip_perc`	Percentage played	`wt.clip_perc` identifies the percentage of the video that the viewer has played.
`wt.clip_player`	Player name	`wt.clip_player` identifies the name of the video player.
`wt.clip_player_res`	Player resolution	`wt.clip_player_res` indicates the video player's resolution in pixel height x width.
`wt.clip_provider`	Video provider	`WT.clip_provider` indicates the host on which the video is located
`wt.clip_res`	Video resolution	`wt.clip_res` indicates the resolution of the video expressed as height x width in pixels.
`wt.clip_secs`	Playhead in seconds	`wt.clip_secs` indicates the video's playhead position in seconds.
`wt.clip_src`	Video URL	`wt.clip_src` provides the URL of the video.
`wt.clip_t`	Media type	`wt.clip_t` identifies the type of media, such as Flash or HTML5, depending on what type of player is being used.
`wt.clip_tv`	Video tag plugin version	`wt.clip_tv` provides the version of the video tag plugin.
`wt.clip_vol`	Volume level	`wt.clip_vol` provides the volume of the video on a scale from 1 through 100.
`wt.dl`	Event tracking	`wt.dl` specifies a numeric identifier for the kind of event tracked, which are used for event-level filtering and reporting.

Configuration options

You can customize the YouTube video tracking plugin configuration with the following options, some of which generate certain key parameters.

Option	Data type	Description	Key parameters
`beacon`	boolean	When set to `true` (the default), a time beacon event is sent every `beaconRate` seconds. If only quartile reporting is needed, set this option to `false` to disable beacon tracking.	`wt.clip_ev:Beacon`
`beaconRate`	integer	The interval between beacons in seconds values (from 0 through 65000). Set this value to the maximum granularity of the reporting you require to make business decisions. The default value is 60.
`bins`	integer	Sets a bin range for duration tracking in seconds (from 0 through 65000) for categorizing videos by time duration buckets or bins. The default value is 15.	`wt.clip_duration_n:value`
`buffering`	boolean	When set to `true`, buffering events are tracked. When set to `false` (the default), buffering events are not tracked.	`wt.clip_ev:Buffering`
`cued`	boolean	When set to `true`, cued events are tracked. When set to `false` (the default), cued events are not tracked.	`wt.clip_ev:Cued`
`enable`	boolean	Enables the YouTube video tracking plugin when set to `true` (the default)
`load`	boolean	When set to `true`, load events are tracked. The default value is `false`.	`wt.clip_ev:Load`
`loadAPI`	boolean	When set to `true`, the YouTube iframe player API code is loaded. Example: `"config" : { "ora-plugins" : { yt: {loadAPI:true} } }` Important: You should load the YouTube iframe player API in the `<head>` of the page to increase site security and tracking reliability. You should only use the `loadAPI` configuration option if you cannot otherwise load the YouTube iframe player API code. The default value is `false`.
`loadMeta`	boolean	When set to `true` (the default), loaded meta events are generated.	`wt.clip_ct:content_type` `wt.clip_duration:seconds` `wt.clip_duration_n:value` `wt.clip_ev:LoadMeta` `wt.clip_player:player_name` `wt.clip_player_res:heightxwidth` `wt.clip_provider:provider_name` `wt.clip_res:heightxwidth` `wt.clip_t:media_type`
`mode`	string	You can specify the following `mode` options: `default`: When the YouTube Video tag plugin loads in `default` mode, it binds tracking to the YouTube player links that it finds in the markup on the page. If you are dynamically inserting the player into the markup, `default` mode typically does not work because the player may not be present when the plugin loads. Example: `"config" : { "ora-plugins" : { yt: {} } }` `manual`: Allows you to manually bind tracking to YouTube players. Use this mode if the page is instantiating its own `YT.Player` objects. In this case, the plugin cannot automatically track the players, so the `YT.Player` objects must be passed to the YouTube Video tag plugin. See the sample implementation, which shows how to do this using the `addYTPlayer()` method. Example: `"config" : { "ora-plugins" : { yt: {mode:'manual'} } }` `poll`: When the YouTube Video tag plugin loads in `poll` mode, it will poll the page for new players every 250 milliseconds and it will bind the tracking to a found player. If the player is removed, it will unbind the tracking from the player. This is the best mode if you are dynamically building pages. However, `poll` mode does consume a small amount of processor time to check the page and determine if new players are being added. Example: `"config" : { "ora-plugins" : { yt: {mode:'poll'} } }`
`pause`	boolean	When set to `true` (the default), pause and resume events are tracked.	`wt.clip_ev:Pause` `wt.clip_ev:Resume`
`pctInc`	integer	Sets the quartile tracking percentage increments, which is expressed as an integer from 0 through 100. For dectile tracking (every 10 percent), set this option to 10. The default value is 25.
`quartile`	boolean	When set to `true` (the default value), the YouTube video tracking plugin uses quartile event tracking and the player will send data at quartile points defaulted to 25, 50, 75, and 100%. The calculation for quartile is: (current position / video duration)100* wt.clip_secs = (Math.floor(((e.currentTime) * 100) / 1) / 100); wt.clip_perc = Math.floor((e.currentTime / e.duration ) * 100); wt.clip_perc = Math.floor(WT.clip_perc / config.pctInc) * config.pctInc;	`wt.clip_perc:quartile`
`seek`	boolean	When set to `true` (the default value), seek events are tracked.	`wt.clip_ev:Seek`
`trackCallback`	string	Modifies the tracking callback function from an Infinity `ORA.click` call to use a custom method. For details, see the samples.
`transformCallback`		Adds in a transform so the data can be customized before sending (standard Oracle transform)
`volume`	boolean	When set to `true` (the default value), volume events are tracked and the YouTube video tracking plugin generates parameters.	`wt.clip_ev:Volume` `wt.clip_vol:level`

Sample implementations

Auto poll example

<!DOCTYPE html>
<html>
<title>yt auto poll page </title>

<body>
    <!-- 1. The <iframe> (and video player) will replace this <div> tag. -->
    <script>
        var tag = document.createElement('script'); tag.src = "//www.youtube.com/iframe_api"; var firstScriptTag = document.getElementsByTagName('script')[0]; firstScriptTag.parentNode.insertBefore(tag, firstScriptTag);
    </script>
    <div id="player">
        <iframe width="640" height="360" class="embed-responsive-item video-frame" id="widget4" src="//www.youtube.com/embed/NzbYTJAR0Ac?enablejsapi=1&origin=http://webtrends.com" frameborder="0" allowfullscreen=""></iframe>
    </div>

    <script src="http://devc.webtrends.com/c2/acs/account/hnzfckc36p/js/odc.js"></script>
</body>

</html>

Manual mode example

$().ready(function () {// dynamically insert the player
    setTimeout(function () {
        $('#player4').append('<h3>Dynamically inserted player using manual plugin trigger</h3><br><iframe id="ytplayer4" width="640" height="360" id="widget4" src="//www.youtube.com/embed/NzbYTJAR0Ac?enablejsapi=1" frameborder="0" allowfullscreen=""></iframe>')
            var player1 = new YT.Player('ytplayer4', {
            height: '390',
            width: '640',
            videoId: 'NzbYTJAR0Ac',
            playerVars: {
                fs: 0  
            },  
            events: {
               'onReady': function(event){
               ORA.analytics.plugins.yt.addPlayer(event.target);
               },
            }  
        });
    }, 10000);
    });

Poll mode example

<!DOCTYPE html>
<html>
<title>Page with Poll Mode</title>
<script>
    var tag = document.createElement('script');

        tag.src = "//www.youtube.com/iframe_api";
        var firstScriptTag = document.getElementsByTagName('script')[0];
        firstScriptTag.parentNode.insertBefore(tag, firstScriptTag);
</script>

<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.3/jquery.min.js"></script>

<body>
    <br> Dynamic Video Insertion after 3 seconds<br>Plugin manual <br>
    <script>
        $().ready(function () {// dynamically insert the player
            setTimeout(function () {
                $('#player').append('<iframe width="640" height="360" class="embed-responsive-item video-frame" id="widget4" src="//www.youtube.com/embed/NzbYTJAR0Ac?enablejsapi=1&origin=http://webtrends.com" frameborder="0" allowfullscreen=""></iframe>')
            }, 3000);
        });
    </script>

    <div id="player">

    </div>

    <script src="http://devc.webtrends.com/c2/acs/account/hnzfckc36p/js/odc.js"></script>
</body>

</html>

trackCallback samples

To send data via Tealium:

trackCallback:function(s){ 
    utag.data.event_type='video';
    var mergedUDO=jQuery.extend(utag.data,states.data.wt);
    utag.link(mergedUDO);
};

To send data via postMessage:

trackCallback: function (t) {
    var payload = JSON.stringify({action: 'MultiTrack', data: [t.argsa]});
    _window.parent.postMessage(payload, "*");
};

The following objects are passed to the callback function:

element: this,                       // current environment
argsa: tags,                         // Infinity tags to be sent
transform: config.transformCallback, // transform for legacy v10 tag
data: states.data.wt,                // raw tag data in form ["wt"].['clip_*] format
videoEle: e                          // video element reference that's created the event

Errors

The YouTube video tracking plugin can send the following error messages via the wt.clip_ev and wt.dl parameters.

Error - Request contains invalid parameter
Error - Content cannot be played in an HTML5 Player
Error - Requested video was not found
Error - Video can not be played in embedded players
Error - Unknown video error

Learn more

Infinity Module Plugins

YouTube Player API reference