Data Collection for Media Players

Intellectual Property

Protected by patents in the U.S. and Europe:

US10430037, EP2684143, US8365188, EP1997041, US8880710, EP1979840, US8898309, EP1979839

A hands on guide to using the Celebrus data collection for media players.

1. Introduction

The Celebrus data collection can collect events from the following media players.

HTML5 media player
Windows Media Player
QuickTime
RealPlayer
Silverlight
YouTube

2. Automatic data collection

The Celebrus HTML5 CSA automatically collects events from media players. Supported media players include:

HTML5 media player
Windows Media Player
QuickTime
RealPlayer
Silverlight

Prerequisites for media collection are that the embedded player within the web page has an ID attribute, and that the Celebrus Collection Service is configured to collect media events, and the media player.

Restrictions apply for OS, browser, and media players combinations due to the media player technology, though in practice these pose little problem:

Windows Media Player events are collected only in Internet Explorer and Firefox on Windows.
QuickTime events are collected in Internet Explorer, Firefox, and Google Chrome on Windows and in Safari on Mac.
Real Player state change events are collected only in Internet Explorer on Windows except for Internet Explorer 7.
Silverlight events are only collected if MediaElement controls within the web page are visible to the CSA.

3. YouTube Player support

The CSA has been modified to allow collection and analysis of events from YouTube Player controls embedded in the user’s page. YouTube recommend the use of the IFrame Player API to embed YouTube content in a web page.

3.1. IFrame Player API support

The standard example for using the IFrame Player API describes how the developer can create a JavaScript reference to the embedded player in the onYouTubeIframeAPIReady function like this:

var player;
 function onYouTubeIframeAPIReady() {
      player = new YT.Player('player', {
         height: '390',
         width: '640',
         videoId: 'M7lc1UVf-VE',
         events: {
          'onReady': onPlayerReady,
          'onStateChange': onPlayerStateChange
          }
      });
 }

The collection of events from the YouTube IFrame player requires a further small change once the JavaScript reference to the player has been created - it is necessary for the developer to call a window-level CSA function which tracks the state change events for the player, passing the player reference as an argument.

The CSA function which tracks the Iframe player state change events is:

[csaName]CelebrusApi.trackYouTubeIframePlayer(playerRef, playerId)

where csaName indicates the CSA name assigned for the Collection Server, playerRef is a reference to the player object generated in the onYouTubeIframeAPIReady function and playerId is the ID attribute assigned for the player.

The following example shows the extra lines to be added to the onYouTubeIframeAPIReady function in red, where the CSA Name being used is csaName:

 var player;
 function onYouTubeIframeAPIReady() {
    player = new YT.Player('player', {
         height: '390',
         width: '640',
         videoId: 'M7lc1UVf-VE',
         events: {
            'onReady': onPlayerReady,
            'onStateChange': onPlayerStateChange
         }
    });

    if([csaName]CelebrusApi)
    {
      [csaName]CelebrusApi.trackYouTubeIframePlayer(player, 'player');
    }
 }

3.2. JavaScript API support

This support is based on the YouTube JavaScript API and requires minimal changes to the way the YouTube media is embedded in the page. For further details please consult the YouTube JavaScript API reference pages.

In order to collect YouTube events the player must be assigned an ID attribute that uniquely identifies the player instance in the page.

Enabling the collection of events from a YouTube player requires three steps:

Add the URL parameters enablejsapi=1 to the player’s URL
Add the URL parameter playerapiid=[id] to the player’s URL, where [id] indicates the ID attribute assigned the YouTube player instance to be tracked
Set the allowScriptAccess parameter of the YouTube player object to always. The allowScriptAccess parameter in the code is needed to allow the player SWF to call functions on the containing HTML page, since the player is hosted on a different domain from the HTML page.

For example if you use SWFObject to embed YouTube Player in the page their final code may look like this:

<div id="ytapiplayer">
 You need Flash player 8+ and JavaScript enabled to view this video.
</div>

<script type="text/javascript">
 // <![CDATA[
 // allowScriptAccess must be set to allow the Javascript from one
 // domain to access the swf on the youtube domain
 var params = {
   allowScriptAccess: "always",
   bgcolor: "#cccccc"
 };

 // This sets the ID of the object or embed tag to 'myytplayer'.
 // You then use this id to access the SWF and make calls to the player's API
 var atts = {
   id: "myytplayer"
 };

 swfobject.embedSWF("http://www.youtube.com/v/Ote5aOIPpJQ?border=0&enablejsapi=1&*playerapiid=myytplayer*", "ytapiplayer", "425", "344", "8", null, null, params, atts);
 //]]>
</script>

The allowScriptAccess parameter has been added and assigned a value of always.

An ID attribute of myytplayer has been assigned to the player instance embedded.

The extra URL parameters have been added to the player’s URL. Note that the playerapiid parameter added matches the ID assigned to the player.

If a page does not use SWFObject, the following example shows the object tag as it would appear when embedded directly into the page:

<object type="application/x-shockwave-flash" id="myytplayer" style="width:330px; height:198px;" data="http://www.youtube.com/v/Ote5aOIPpJQ?border=0&enablejsapi=1&playerapiid=myytplayer">
 <param name="movie" value="http://www.youtube.com/v/Ote5aOIPpJQ?border=0&enablejsapi=1&playerapiid=myytplayer" />
 <param name="wmode" value="transparent" />
<param name="allowScriptAccess" value="always" />
</object>

An ID attribute of myytplayer has been assigned to the player instance embedded.

The extra URL parameters have been added to the player’s URL. Note that the playerapiid parameter added matches the ID assigned to the player. Note also that the parameters have been added in both places where the URL is specified - once in the data attribute of the object tag and once in the movie parameter of the object tag.

The allowScriptAccess parameter has been added and assigned a value of always.