Introduction

Asynchronous JavaScript ad serving will trigger events that may be listened to with the EventTarget.addEventListener() method. The triggered events use the CustomEvent API, and the event data will be found in the event.detail property.

Review the Detailed examples at the end of this guide for code snippets.

Events

There are four events you may listen to:

• Request
• Response
• Load
• Viewable

---

Request

This event is triggered when the ad request is first sent. This event will also be triggered for each refresh on refreshing ads.

You may listen to this event by either adding a listener to a specific zone div, or listening globally.

Examples

Attaching an event to a placement container element.

var element = document.getElementById( PLACEMENT_DIV_ID_HERE );
element.addEventListener(AdButler.EVENTS.REQUEST, function(e) { console.log(e.type, e.detail); });

Listening for the event globally.

AdButler.addEventListener(AdButler.EVENTS.REQUEST, function(e) { console.log(e.type, e.detail); });

Properties

List of properties found in the event.detail object.

Property	Type	Description
elementID	string	The ID of the DOM element containing the ad
place	int	The zone's place ID
refreshNumber	int	The refresh number for the current ad request. The first request will be 0 and subsequent refreshes will be one refresh number higher. This can be used to associate a set of request/response/load/viewable events to a particular refresh of a zone.
size	string	The dimensions of the zone as pixel width x height, e.g. 300x250
zoneID	int	The zone ID of the zone that is requesting an ad.

---

Response

This event is triggered when the ad request has returned a response. This event will also be triggered for each refresh on refreshing ads.

You may listen to this event by either adding a listener to a specific zone div, or listening globally.

Examples

Attaching an event to a placement container element.

var element = document.getElementById( PLACEMENT_DIV_ID_HERE );
element.addEventListener(AdButler.EVENTS.RESPONSE, function(e) { console.log(e.type, e.detail); });

Listening for the event globally.

AdButler.addEventListener(AdButler.EVENTS.RESPONSE, function(e) { console.log(e.type, e.detail); });

Properties

List of properties found in the event.detail object.

Property	Type	Description
elementID	string	The ID of the DOM element containing the ad
place	int	The zone's place ID
refreshNumber	int	The refresh number for the current ad request. The first request will be 0 and subsequent refreshes will be one refresh number higher. This can be used to associate a set of request/response/load/viewable events to a particular refresh of a zone.
size	string	The dimensions of the zone as pixel width x height, e.g. 300x250
zoneID	int	The zone ID of the zone that is requesting an ad.
filled	boolean	Whether or not the ad response was filled. This will be true when an ad is returned and false when no ad is returned.

---

Load

This event is triggered once the ad has loaded. This will include the image load time for an image ad. This event will also be triggered for each refresh on refreshing ads.

You may listen to this event by either adding a listener to a specific zone div, or listening globally.

Examples

Attaching an event to a placement container element.

var element = document.getElementById( PLACEMENT_DIV_ID_HERE );
element.addEventListener(AdButler.EVENTS.LOAD, function(e) { console.log(e.type, e.detail); });

Listening for the event globally.

AdButler.addEventListener(AdButler.EVENTS.LOAD, function(e) { console.log(e.type, e.detail); });

Properties

List of properties found in the event.detail object.

Property	Type	Description
elementID	string	The ID of the DOM element containing the ad
place	int	The zone's place ID
refreshNumber	int	The refresh number for the current ad request. The first request will be 0 and subsequent refreshes will be one refresh number higher. This can be used to associate a set of request/response/load/viewable events to a particular refresh of a zone.
size	string	The dimensions of the zone as pixel width x height, e.g. 300x250
zoneID	int	The zone ID of the zone that is requesting an ad.

---

Viewable

This event is triggered once the ad has been registered as viewable. This event will also be triggered for each refresh on refreshing ads.

You may listen to this event by either adding a listener to a specific zone div, or listening globally.

Examples

Attaching an event to a placement container element.

var element = document.getElementById( PLACEMENT_DIV_ID_HERE );
element.addEventListener(AdButler.EVENTS.VIEWABLE, function(e) { console.log(e.type, e.detail); });

Listening for the event globally.

AdButler.addEventListener(AdButler.EVENTS.VIEWABLE, function(e) { console.log(e.type, e.detail); });

Properties

List of properties found in the event.detail object.

Property	Type	Description
elementID	string	The ID of the DOM element containing the ad
place	int	The zone's place ID
refreshNumber	int	The refresh number for the current ad request. The first request will be 0 and subsequent refreshes will be one refresh number higher. This can be used to associate a set of request/response/load/viewable events to a particular refresh of a zone.
size	string	The dimensions of the zone as pixel width x height, e.g. 300x250
zoneID	int	The zone ID of the zone that is requesting an ad.

---

Detailed examples

Specific ad container element

To use this example, you should replace PLACEMENT_DIV_ID_HERE with the DOM ID of the placement container div. Implementation of the event handlers is up to the end user.

<script>
var AdButler = AdButler || {};
AdButler.ads = AdButler.ads || [];

AdButler.ads.push(function () {
    var element = document.getElementById( PLACEMENT_DIV_ID_HERE );
    element.addEventListener(AdButler.EVENTS.REQUEST, function (e) {
        console.log(e.type, e.detail);
    });
    element.addEventListener(AdButler.EVENTS.RESPONSE, function (e) {
        console.log(e.type, e.detail);
    });
    element.addEventListener(AdButler.EVENTS.LOAD, function (e) {
        console.log(e.type, e.detail);
    });
    element.addEventListener(AdButler.EVENTS.VIEWABLE, function (e) {
        console.log(e.type, e.detail);
    });
});
</script>

Global events

This is an example of how to listen to ad events globally. Implementation of the event handlers is up to the end user.

<script>
var AdButler = AdButler || {};
AdButler.ads = AdButler.ads || [];

AdButler.ads.push(function () {
    AdButler.addEventListener(AdButler.EVENTS.REQUEST, function (e) {
        console.log(e.type, e.detail);
    });
    AdButler.addEventListener(AdButler.EVENTS.RESPONSE, function (e) {
        console.log(e.type, e.detail);
    });
    AdButler.addEventListener(AdButler.EVENTS.LOAD, function (e) {
        console.log(e.type, e.detail);
    });
    AdButler.addEventListener(AdButler.EVENTS.VIEWABLE, function (e) {
        console.log(e.type, e.detail);
    });
});
</script>