How to use the Collector Proxy

Native player events (and corresponding metadata) can be dispatched through a Collector Proxy object external to the Datazoom Collector SDK.

To create a new Collector Proxy object, use the datazoom.createCollectorProxy() method provided by the Datazoom Collector SDK.

`HTMLMediaElement` Proxy

The HTML5 HTMLMediaElement interface is clearly documented and well known, so a common approach of sending event/data through proxy is by:

Import the Datazoom Collector SDK which is provisioned to collect from a HTMLMediaElement
Create a Collector Proxy object with the datazoom.createCollectorProxy() method
Invoke datazoom.createContext() with the proxy object in place of a real HTMLMediaElement object
As appropriate, invoke the proxy object’s dispatch() method to trigger native events and update data.

// Create a new proxy object
var media_element_proxy = datazoom.createCollectorProxy();

// Create a collector context to collect from the proxy object
var datazoom_context = datazoom.createContext(media_element_proxy);

// Trigger the HTMLMediaElement "play" event with data updates
media_element_proxy.dispatch("play", {
    media: {
        currentSrc: "https://example.com/stream.m3u8",
        currentTime: 0,
        duration: 300,
        playbackRate: 1.0,
        paused: false,
        volume: 0.5,
        muted: false,
        loop: false
    }
});
...
// Trigger the HTMLMediaElement "timeupdate" event with a new currentTime
media_element_proxy.dispatch("timeupdate", {
    media: {
        currentTime: 1.5
    }
});
...
// Trigger the HTMLMediaElement "error" event with a MediaError object
media_element_proxy.dispatch("error", {
    media: {
        error: {
            code: 2,
            message: "something wrong"
        }
    }
});

Native Events

The event type string (first argument of a dispatch() call) can be one of the following:

Event type	Reference	Description
"play"	MDN	The `paused` property is changed from true to false, as a result of the `play()` method or autoplay
"waiting"	MDN	Playback has stopped because of a temporary lack of data
"playing"	MDN	Playback is first started or restarted (from pause or delay)
"pause"	MDN	When the `paused` property has been changed to true
"seeking"	MDN	When a seek operation starts
"seeked"	MDN	When a seek operation completed
"ended"	MDN	Playback has stopped because the end of the media was reached
"error"	MDN	When the resource could not be loaded due to an error
"durationchange"	MDN	When the `duration` property has been updated
"ratechange"	MDN	When the playback rate has changed
"timeupdate"	MDN	When the `currentTime` property has been updated

Data Payload Schema

{
    media: {
        currentSrc: ...,
        currentTime: ...,
        duration: ...,
        playbackRate: ...,
        paused: ...,
        error: ...,
        volume: ...,
        muted: ...,
        loop: ...,
        readyState: ...,
        videoWidth: ...,
        videoHeight: ...,
        offsetWidth: ...,
        offsetHeight: ...,
        boundingClientRect: ...
    }
}

Key	Reference	Description
currentSrc	MDN	The absolute URL of the chosen media resource
currentTime	MDN	The current playback time in seconds
duration	MDN	The length of the element's media in seconds
playbackRate	MDN	The rate at which the media is being played back (1.0 indicates normal speed)
paused	MDN	Whether the media element is paused
error	MDN	The MediaError object for the most recent error, or null
volume	MDN	The volume at which the media is being played (between 0 and 1)
muted	MDN	Whether the media element is muted
loop	MDN	Whether the media element should start over when it reaches the end
readyState	MDN	The readiness state of the media (0 - 4)
videoWidth	MDN	The intrinsic width of the video (i.e., the width of the media in its natural size)
videoHeight	MDN	The intrinsic height of the video (i.e., the height of the media in its natural size)
offsetWidth	MDN	The layout width of the media element
offsetHeight	MDN	The layout height of the media element
boundingClientRect	MDN	The latest return value from the media element’s getBoundingClientRect() call, providing location information relative to the viewport (for Viewability related calculations) The collector will use only the `left`, `right`, `top`, and `bottom` fields of the Rect object and ignore the rest

IMA `AdsManager` Proxy

To send event/data through proxy to process them in a way compatible to IMA:

Create a Collector Proxy object with the datazoom.createCollectorProxy() method
Invoke the Datazoom collector context object’s attachImaAdsManager() method with the proxy object in place of a real AdsManager object
As appropriate, invoke the proxy object’s dispatch() method to trigger native events and update data.

// Create a new proxy object
ads_manager_proxy = datazoom.createCollectorProxy();

// Attach the proxy object to the collector context for ad data collection
datazoom_context.attachImaAdsManager(ads_manager_proxy);

// Trigger the AdsManager "loaded" event with data updates
ads_manager_proxy.dispatch("loaded", {
    ima: {
        adsManager: {
            volume: 0,
        },
        ad: {
            adId: "697200496",
            adSystem: "GDFP",
            creativeId: "57860459056",
            duration: 10,
            skipTimeOffset: 5,
            vastMediaBitrate: 533,
            vastMediaWidth: 1280,
            vastMediaHeight: 720,
            adPodIndex: 0,
            adTimeOffset: 0,
            ...
        }
    }
});
...
// Trigger the AdsManager "adProgress" event with a new currentTime
ads_manager_proxy.dispatch("adProgress", {
    ima: {
        adsManager: {
            currentTime: 1.5
        }
    }
};
...
// Trigger the AdsManager "adError" event with error details
ads_manager_proxy.dispatch("adError", {
    ima: {
        error: {
            code: 123,
            message: "something wrong"
        }
    }
}

Native Events

The event type string (first argument of a dispatch() call) can be one of the following:

Event type	Reference	Description
"click"	IMA	CLICK: Fired when the ad is clicked
"start"	IMA	STARTED: Fired when the ad starts playing
"adProgress"	IMA	AD_PROGRESS: Fired when the ad's current time value changes
"adBuffering"	IMA	AD_BUFFERING: Fired when the ad has stalled playback to buffer
"impression"	IMA	IMPRESSION: Fired when the impression URL has been pinged
"pause"	IMA	PAUSED: Fired when the ad is paused
"resume"	IMA	RESUMED: Fired when the ad is resumed
"complete"	IMA	COMPLETE: Fired when the ad completes playing
"loaded"	IMA	LOADED: Fired when ad data is available
"allAdsCompleted"	IMA	ALL_ADS_COMPLETED: Fired when the ads manager is done playing all the valid ads in the ads response, or when the response doesn't return any valid ads
"skip"	IMA	SKIPPED: Fired when the ad is skipped by the user
"volumeChange"	IMA	VOLUME_CHANGED: Fired when the ad volume has changed
"adError"	IMA	AD_ERROR: Fired when an error occurred while the ad was loading or playing

Data Payload Schema

{
    ima: {
        adsManager: {
            volume: ...,
            currentTime: ...
        },
        ad: {
            adId: ...,
            adSystem: ...,
            advertiserName: ...,
            creativeId: ...,
            dealId: ...,
            duration: ...,
            skipTimeOffset: ...,
            vastMediaBitrate: ...,
            vastMediaWidth: ...,
            vastMediaHeight: ...,
            wrapperAdIds: ...,
            wrapperAdSystems: ...,
            wrapperCreativeIds: ...,
            clickThroughUrl: ...,
            adPodIndex: ...,
            adTimeOffset: ...
        },
        error: {
            code: ...,
            message: ...,
            innerError: ...
        }
    }
}

Key	Reference	Description
adsManager.volume	IMA	The volume of the current ad, from 0 (muted) to 1 (loudest)
adsManager.currentTime	IMA	The current time of the currently playing ad
ad.adId	IMA	The ID of the ad
ad.adSystem	IMA	The source ad server of the ad
ad.advertiserName	IMA	The advertiser name
ad.creativeId	IMA	The ID of the selected creative for the ad
ad.dealId	IMA	The first deal ID present in the wrapper chain for the current ad, starting from the top
ad.duration	IMA	The selected creative duration in seconds
ad.skipTimeOffset	IMA	The number of seconds of playback before the ad becomes skippable
ad.vastMediaBitrate	IMA	The bitrate for the selected media file as listed in the vast response
ad.vastMediaWidth	IMA	The VAST media width of the selected creative
ad.vastMediaHeight	IMA	The VAST media height of the selected creative
ad.wrapperAdIds	IMA	Ad IDs (array of strings) used for wrapper ads, starts at the inline ad (innermost) and traverses to the outermost wrapper ad
ad.wrapperAdSystems	IMA	Ad systems (array of strings) used for wrapper ads, starts at the inline ad and traverses to the outermost wrapper ad
ad.wrapperCreativeIds	IMA	Selected creative IDs (array of strings) used for wrapper ads, starts at the inline ad and traverses to the outermost wrapper ad
ad.clickThroughUrl		The target URL to open when the user clicks on the ad
ad.adPodIndex	IMA	The index of the ad pod (pre-roll: 0, mid-rolls: 1 - n, post-roll: -1)
ad.adTimeOffset	IMA	The content time offset at which the current ad pod was scheduled (pre-roll: 0, mid-rolls: scheduled time, post-roll: -1)
error.code	IMA	The error code (a number)
error.message	IMA	The message for this error
error.innerError	IMA	The inner error that caused this error

Articles in this section

`HTMLMediaElement` Proxy

Native Events

Data Payload Schema

IMA `AdsManager` Proxy

Native Events

Data Payload Schema

Comments

Articles in this section

HTMLMediaElement Proxy

Native Events

Data Payload Schema

IMA AdsManager Proxy

Native Events

Data Payload Schema

Related articles

`HTMLMediaElement` Proxy

IMA `AdsManager` Proxy