##dz-db-collector-details

Plugin Integration

Datazoom provides plugins for data collection through our Beacon Services. Integrate the Shaka Player plugin into your web application with the following snippet:

 <script src='https://platform.datazoom.io/beacon/v1/config?configuration_id=CONFIG_ID'></script>

Insert this JS line into your HTML
Replace the CONFIG_ID value with the collector configuration ID.

This inserts Datazoom's data collection SDK into the page.

Additional Parameters

The Shaka Player plugin can be integrated into your HTML along with additional parameters. For example, the cmcd_mode parameter overrides the mode of transmitting CMCD data to CDN:

<script src='https://platform.datazoom.io/beacon/v1/config?configuration_id=CONFIG_ID&cmcd_mode=header'></script>

Normally the CMCD data, if enabled, are transmitted to CDN as query strings on each of the request URLs. By specifying header for the cmcd_mode parameter as above, the same data are transmitted to CDN as HTTP headers instead.
The CDN must be configured to support CORS preflight requests, in order to allow CMCD headers.
The CONFIG_ID value above should be replaced with the collector configuration ID as usual.

Activate Data Collection for a Shaka Player

Activate data collection by passing player instance only.

context = datazoom.createContext(player);

for example:

<!DOCTYPE html>
<html lang="en">

<head>
    <title>Shaka Player Test Video</title>
    <link rel="stylesheet" href="https://ajax.googleapis.com/ajax/libs/shaka-player/3.1.0/controls.css">
    <!-- THE SHAKA PLAYER CDN -->
    <script src="https://ajax.googleapis.com/ajax/libs/shaka-player/3.1.0/shaka-player.ui.js"></script>
    <!-- THE DATAZOOM BEACON SCRIPT -->
    <script src="https://platform.datazoom.io/beacon/v1/config?configuration_id=CONFIG_ID"></script>
</head>

<body>
    <p>
        This example demonstrates the basic use of the Datazoom SDK with the SHAKA
        player
    </p>
    <div data-shaka-player-container style="max-width: 40em" data-shaka-player-cast-receiver-id="1BA79154">
        <video data-shaka-player id="video" style="width: 100%; height: 100%"></video>
    </div>
    <script>
        async function initPlayer() {
            var video_url = "https://storage.googleapis.com/shaka-demo-assets/angel-one/dash.mpd"
            const video = document.getElementById("video");
            var ui = video["ui"];;
            // Create a Controls instance.
            var controls = ui.getControls();
            // Create a Player instance.
            var player = controls.getPlayer();
            window.player = player;
            //Activates data collection
            datazoom.createContext(player);
            try {
                await player.load(video_url);
                // This runs if the asynchronous load is successful.
                console.log("The video has now been loaded!");
            } catch (e) {
                // onError is executed if the asynchronous load fails.
                onError(e);
            }
        }

        function initApp() {
            // Install built-in polyfills to patch browser incompatibilities.
            shaka.polyfill.installAll();
            // Check to see if the browser supports the basic APIs Shaka needs.
            if (shaka.Player.isBrowserSupported()) {
                // Everything looks good!
                document.addEventListener('shaka-ui-loaded', initPlayer);
            } else {
                // This browser does not have the minimum set of APIs we need.
                console.error("Browser not supported!");
            }
        }

        function onErrorEvent(event) {
            // Extract the shaka.util.Error object from the event.
            onError(event.detail);
        }

        function onError(error) {
            // Log the error.
            console.log("Error code", error.code, "object", error);
        }
        initApp();
    </script>
</body>

</html>

Activate data collection by passing player instance and controls instance

context = datazoom.createContext({
    player: my_player,
    controls: my_controls
});

for example:

<!DOCTYPE html>
<html lang="en">

<head>
    <title>Shaka Player Test Video</title>
    <link rel="stylesheet" href="https://ajax.googleapis.com/ajax/libs/shaka-player/3.1.0/controls.css">
    <!-- THE SHAKA PLAYER CDN -->
    <script src="https://ajax.googleapis.com/ajax/libs/shaka-player/3.1.0/shaka-player.ui.js"></script>
    <!-- THE DATAZOOM BEACON SCRIPT -->
    <script src="https://platform.datazoom.io/beacon/v1/config?configuration_id=CONFIG_ID"></script>

</head>

<body>
    <p>
        This example demonstrates the basic use of the Datazoom SDK with the SHAKA
        player
    </p>
    <div data-shaka-player-container style="max-width: 40em" data-shaka-player-cast-receiver-id="1BA79154">
        <video data-shaka-player id="video" style="width: 100%; height: 100%"></video>
    </div>
    <script>
        async function initPlayer() {
            const video = document.getElementById("video");
            var video_url = "https://storage.googleapis.com/shaka-demo-assets/angel-one/dash.mpd"
            var ui = video["ui"];
            // Create a Controls instance.
            var my_controls = ui.getControls();
            // Create a Player instance.
            var my_player = my_controls.getPlayer();
            window.my_player = my_player;
            datazoom.createContext({
                player: my_player,
                controls: my_controls
            });
            try {
                await my_player.load(video_url);
                // This runs if the asynchronous load is successful.
                console.log("The video has now been loaded!");
            } catch (e) {
                // onError is executed if the asynchronous load fails.
                onError(e);
            }
        }

        function initApp() {
            // Install built-in polyfills to patch browser incompatibilities.
            shaka.polyfill.installAll();
            // Check to see if the browser supports the basic APIs Shaka needs.
            if (shaka.Player.isBrowserSupported()) {
                // Everything looks good!
                document.addEventListener('shaka-ui-loaded', initPlayer);
            } else {
                // This browser does not have the minimum set of APIs we need.
                console.error("Browser not supported!");
            }
        }

        function onErrorEvent(event) {
            // Extract the shaka.util.Error object from the event.
            onError(event.detail);
        }

        function onError(error) {
            // Log the error.
            console.log("Error code", error.code, "object", error);
        }
        initApp();
    </script>
</body>

</html>

Stop Data Collection

If the data collection must be stopped for any reason, for example after the destruction of the corresponding player instance, invoke the destroy() method of the Datazoom context object as in the following example:

if (my_player) {
    my_player.destroy();
    my_player = null;
}

if (datazoom_context) {
    datazoom_context.destroy();
    datazoom_context = null;
}

NPM (Node Package Manager)

We have made it convenient to manage your Shaka Collector integration by providing NPM (Node Package Manager) support. Please see installation details here.

References:

Shaka Player API Doc : https://shaka-player-demo.appspot.com/docs/api/tutorial-welcome.html

Ad Support - client side ads

Datazoom provides data collection options for Google IMA and Freewheel. By using the integration options described below you can collect a number of ad related events and related metadata to further understand ad performance.

Freewheel

To enable a Datazoom collector to capture the ad related data points, the required steps for a web application differ depending on how the ad framework (e.g., Freewheel) is integrated with the video player. In general, there are two types of integration method between the video player and ad framework:

1. Leverage ad framework integration supported by the video player

Players such as Akamai AMP player, JW Player, THEOplayer, … etc., support Freewheel ad integration as a part or an optional module of the player. Since the corresponding Datazoom collector for the player is prebuilt with knowledge of the player’s ad related features, for a web application who simply leverages the video player for ads, no additional code is required to enable ad data collection in this scenario.

A web application may choose to utilize the video player for the purpose of content presentation only, while building its own ad implementation by utilizing the ad framework directly. In these use cases, the video player has no awareness of the ad implementation and therefore it will fall under the second scenario described below.

2. Ad implementation external to the video player

Players that mainly focus on core playback/streaming functionalities, such as HLS.js player, Dash.js player, or the native HTML5 <video> element, often do not come with ad integration features. For a web application who likes to enable ads independent of the video player, it can choose to utilize the ad framework library (e.g., Freewheel MRM AdManager SDK) directly or bring in some third-party components. In either cases, since it is impossible for the corresponding Datazoom collector to gather ad information through the video player, some provisioning steps (see the section below: Attach the Freewheel Context) will be required to enable ad data collection.

Attach the Freewheel Context

For a web application who enables ads by utilizing Freewheel MRM AdManager SDK directly or through some third-party components, it will be interacting with the Freewheel Context object. This object is responsible for creating ad requests, parsing the ad request responses, and managing the presentation of the resulted ads. Besides, the Freewheel Context object also provides events and metadata regarding the resulted ads and the presentation status.

Therefore, for a Datazoom collector to gather ad information in this scenario, the application should give access by attaching the Freewheel Context object to the collector context as soon as it becomes available. The Datazoom collector context interface expose these methods for this purpose:

// share a Freewheel Context object with the collector context
context.attachFwContext(freewheel_context) {}

// unshare the Freewheel Context object as an optional cleanup step
context.detachFwContext() {}

For example, a video page using HTML5 <video> element and managing Freewheel MRM AdManager SDK directly can set everything up and attach the Freewheel Context object (to the collector context) as below:

// Create the video player and the collector context
var media_element = document.getElementById("video");
var datazoom_context = datazoom.createContext(media_element);

// Create the Freewheel AdManager
var fw_admanager = new tv.freewheel.SDK.AdManager();
fw_admanager.setNetwork(1234);
fw_admanager.setServer("ad_server_url");

// Create the Freewheel Context object
var fw_context = fw_admanager.newContext();
fw_context.setProfile("some_profile");
/* other Freewheel Context configurations
 fw_context.setVideoAsset(...);
 fw_context.setSiteSection(...);
 fw_context.addTemporalSlot(...);
 ...
 */

// Share the Freewheel Context object with the collector context
datazoom_context.attachFwContext(fw_context);

// Request ads
fw_context.submitRequest();

/* other code related to ad presentation and player coordination
 ...
 */

That’s it. The Datazoom collector is now provided with the required access to gather ad related information.

If some third-party component is used to add ad implementation, the best way to enable ad data collection is by querying the underlying Freewheel Context object and attaching it to the collector context in the same way as described above.

Google IMA

To enable a Datazoom collector to capture the ad related data points, the required steps for a web application differ depending on how the ad framework (e.g., IMA) is integrated with the video player. In general, there are two types of integration method between the video player and ad framework:

1. Leverage ad framework integration supported by the video player

Players such as Akamai AMP player, JW Player, Bitmovin Player, Shaka player, … etc., support IMA ad integration as a part or an optional module of the player. Since the corresponding Datazoom collector for the player is prebuilt with knowledge of the player’s ad related features, for a web application who simply leverages the video player for ads, no additional code is required to enable ad data collection in this scenario.

A web application may choose to utilize the video player for the purpose of content presentation only, while building its own ad implementation by utilizing the ad framework directly. In these use cases, the video player has no awareness of the ad implementation and therefore it will fall under the second scenario described below.

2. Ad implementation external to the video player

Players that mainly focus on core playback/streaming functionalities, such as HLS.js player, Dash.js player, or the native HTML5 <video> element, often do not come with ad integration features. For a web application who likes to enable ads independent of the video player, it can choose to utilize the ad framework library (e.g., IMA) directly or bring in some third-party components. In either cases, since it is impossible for the corresponding Datazoom collector to gather ad information through the video player, some provisioning steps (see the section below: Attach IMA Objects) will be required to enable ad data collection.

Attach IMA Objects

For a web application who enables ads by utilizing IMA directly or through some third-party components, it will be interacting with two primary IMA objects mostly:

adsLoader: Usually a singleton object, which handles ad-request (e.g., VAST) transactions based on ad tags given as inputs. Upon each successful completion of an ad-request, one adsManager object is created to oversee the presentation of the resulted ads.
adsManager: An object instance is created upon each successful completion of an ad-request. It provides events and metadata regarding the resulted ads and the presentation status.

Therefore, for a Datazoom collector to gather ad information in this scenario, the application should give access by attaching these IMA objects to the collector context as soon as they become available. The Datazoom collector context interface expose these methods for this purpose:

// share the adsLoader object with the collector context, usually once per context
context.attachImaAdsLoader(adsLoader) {}

// share a adsManager object with the collector context, once per ad-request
context.attachImaAdsManager(adsManager) {}

// unshare adsLoader as an optional cleanup step
context.detachImaAdsLoader() {}

// unshare adsManager as an optional cleanup step
context.detachImaAdsManager() {}

For example, a video page using HTML5 <video> element and managing IMA directly can set everything up and attach the adsLoader (to the collector context) as below:

// Create the video player and the collector context
var media_element = document.getElementById("video");
var datazoom_context = datazoom.createContext(media_element);

// Create the IMA adsLoader
var adContainer = document.getElementById("ad-container");
var adDisplayContainer = new google.ima.AdDisplayContainer(adContainer, media_element);
var adsLoader = new google.ima.AdsLoader(adDisplayContainer);

// Share the adsLoader object with the collector context
datazoom_context.attachImaAdsLoader(adsLoader);

Then, whenever an ad-request is successfully completed, an adsManager object is created and attached to the collector context as below:

adsLoader.addEventListener(google.ima.AdsManagerLoadedEvent.Type.ADS_MANAGER_LOADED,
    function(event) {
        // Create an IMA adsManager
        var adsManager = event.getAdsManager(media_element);
        // Share the adsManager object with the collector context
        datazoom_context.attachImaAdsManager(adsManager);
    }
);

That’s it. The Datazoom collector is now provided with the required access to gather ad related information.

If some third-party component is used to add ad implementation, the best way to enable ad data collection is by querying the underlying IMA adsLoader/adsManager objects and attaching them to the collector context in the same way as described above.

CMCD Support

Datazoom provides two discrete settings that control CMCD data collection, one for a specific player event, “Media Object Request”, and one for the corresponding CDN log response.

Player Collector configuration options

Use this option to enable your configured CDN to collect and return CMCD data, contained in the CMCD node of the log line JSON

Off - no CMCD keys are passed
Lite - only the CMCD keys Session ID (sid) and Request ID (rid) are passed to the CDN via query parameter or request header with every “Media Object Request”.
Full - the full set of keys specified by the CMCD standard are passed to the CDN via query parameter or request header with every “Media Object Request”

Bitmovin and JW Player support only the “Lite” setting above

Data Pipe configuration options

Select the CMCD data points you wish to be included in content requests.

Media Object Request - The video player will emit an event called “media_object_request” that will contain the selected CMCD keys below
CMCD keys - Select the CMCD keys you wish to have included with each Media Object Request