PRODUCT

Amazon Ad Server will be sunset in Q4 2024, please visit this page (AAS offboarding information) for offboarding support resources and sunset FAQs. Details shared on that page represent the most up to date information in the Help Center, if you find disparate information in other resources please default to the information in the AAS offboarding information page accordingly.

Please note that on October 1, 2024, the ability to create new campaigns, placements, and tag managers will be disabled.

Follow

Overview

API Extension is a module that provides additional functionality to the EB object.

Load Module

Before the AdKit declaration in our HTML files, you must include modules and declare them in an array variable called EBModulesToLoad.

The following example loads the EBAPI module for use in an AAS ad.

<script>EBModulesToLoad = ['EBAPI'];</script>

Methods

EB.getAdData

Retrieves a variety of properties for a specific ad. Since ad properties are changed over time, rerunning this function will return the most updated properties. The function returns a string or an object, depending on the number of required properties.

Code Syntax

EB.getAdData(properties)

Parameters

Name

Type

Description

properties

  • String for one parameter

  • Array for multiple parameters

Properties to retrieve.

Example

function checkIfAdKitReady(event) {
    adkit.onReady(getAdInformation);
}

function getAdInformation() {
    // This example will print in the console an object with the adId and the placementId
    console.log(EB.getAdData(['adId','placementId']));
    // This example will print in the console true/false depending if the user clicked in the ad or not
    console.log(EB.getAdData('isClickOccur'));
}

window.addEventListener('load', checkIfAdKitReady);

EB.setAdData

Retrieves a variety of properties for a specific ad. Similar to the getAdData method. The function returns an empty object if successful. Any property that failed will be listed inside the object as key: failReason.

Code Syntax

EB.setAdData(properties)

Parameters

Name

Type

Description

properties

Object

Object with key:value for each property to be changed.

Example

function checkIfAdKitReady(event) {
    adkit.onReady(setAdInformation);
}

function setAdInformation() {
    // This example will set as myName the value 'customizedName' within the ad properties
    EB.setAdData({
        myName: "customizedName"
    });
}

window.addEventListener('load', checkIfAdKitReady);

EB.clip

Use CSS clip to collapse/resize the given element with the specified dimensions.

Code Syntax

EB.clip(element, top, right, bottom, left)

Parameters

Name

Type

Description

element

HTML element

HTML element to be clipped.

top

Number

Distance from top edge to clip.

right

Number

Distance from right edge to clip.

bottom

Number

Distance from bottom edge to clip.

left

Number

Distance from left edge to clip.

Example

function checkIfAdKitReady(event) {
    adkit.onReady(clipElement);
}

function clipElement() {
    // This example will clip an element called banner
    var banner = document.getElementById("banner");
    EB.clip(banner, 0, 300, 50, 0);
}

window.addEventListener('load', checkIfAdKitReady);

EB.unclip

Removes CSS clip style from an element by applying the value rect (auto auto auto auto) to it.

Code Syntax

EB.unclip(element)

Parameters

Name

Type

Description

element

HTML element

HTML element to be unclipped.

Example

function checkIfAdKitReady(event) {
    adkit.onReady(unclipElement);
}

function unclipElement() {
    // This example will remove the clip to an element called banner
    var banner = document.getElementById("banner");
    EB.unclip(banner);
}

window.addEventListener('load', checkIfAdKitReady);

EB.getClipTag

Generates a string, in the correct format, to be applied to the CSS clip property. Returns a string with the necessary clip format, rect(0px 300px 250px 0px) .

Code Syntax

EB.getClipTag(top, right, bottom, left)

Parameters

Name

Type

Description

top

Number

Distance from top edge to clip.

right

Number

Distance from right edge to clip.

bottom

Number

Distance from bottom edge to clip.

left

Number

Distance from left edge to clip.

Example

function checkIfAdKitReady(event) {
    adkit.onReady(getClippingFormat);
}

function getClippingFormat() {
    // This example will print in the console 'rect(0px 300px 50px 0px)'
    console.log(EB.getClipTag(0, 300, 50, 0));
}

window.addEventListener('load', checkIfAdKitReady);

EB.hasClass

Indicates whether an element, or list of elements, has a specific class attribute, or list of such classes.

Code Syntax

EB.hasClass(elements, classNames, requireAll)

Parameters

Name

Type

Description

elements

  • HTML element or ID

  • Array with HTML elements or IDs

Elements from which to look for the class. You can supply the HTMLElement, its ID, or an array of HTMLElement/IDs.

classNames

  • String for a single class

  • classArray for multiple classes

Classes to search for from the elements. You can supply a single string or an array of strings.

requireAll

Boolean/Optional

(Optional) Determines whether to check if all of the submitted elements have the submitted classes, or if any of them have submitted classes. Default is true.

Example

function checkIfAdKitReady(event) {
    adkit.onReady(checkClasses);
}

function checkClasses() {
    // This example will print in the console depending on if the banner element contains the class notVisible
    console.log(EB.hasClass("banner", "notVisible", false));
}

window.addEventListener('load', checkIfAdKitReady);

EB.setClass

Sets one or more class attributes to one or more HTML elements.

Code Syntax

EB.setClass(elements, classNames, shouldReplace)

Parameters

Name

Type

Description

elements

  • HTML element or ID

  • Array with HTML elements or IDs

Elements from which to look for the class. You can supply the HTMLElement, its ID, or an array of HTMLElement/IDs.

classNames

  • String for a single class

  • classArray for multiple classes

Classes to search for from the elements. You can supply a single string or an array of strings.

shouldReplace

Boolean | Optional

(Optional) Determines whether to replace the existing class on the element or add to it. Default value is false; the supplied class will be added to any existing classes.

Example

function checkIfAdKitReady(event) {
    adkit.onReady(addClass);
}

function addClass() {
    // This example will assign the class isVisible to the element with id 'banner'    
console.log(EB.setClass("banner", "isVisible", false));
}

window.addEventListener('load', checkIfAdKitReady);

EB.removeClass

Removes a class attribute from an HTML element.

Code Syntax

EB.removeClass(elements, classNames)

Parameters

Name

Type

Description

elements

  • HTML element or ID

  • Array with HTML elements or IDs

Elements from which to look for the class. You can supply the HTMLElement, its ID, or an array of HTMLElement/IDs.

classNames

  • String for a single class

  • classArray for multiple classes

Classes to search for from the elements. You can supply a single string or an array of strings.

Example

function checkIfAdKitReady(event) {
    adkit.onReady(deleteClass);
}

function deleteClass() {
    // This example will remove the class isVisible to the element with id 'banner'
    console.log(EB.removeClass("banner", "isVisible"));

}
window.addEventListener('load', checkIfAdKitReady);

EB.getCustomVar

Retrieves the current value of a custom variable from the ad. Custom variables can be defined in the ad at runtime or in Amazon Ad Server (AAS) beforehand. The function returns the value of the custom variable, if already defined, or the default value, if passed as a parameter in the function.

Code Syntax

EB.getCustomVar( var_name, default)

Parameters

Name

Type

Description

var_name

String

Name of the custom variable to retrieve.

default

Optional

  • String

  • Number

  • Array

  • Object

Default value to be returned if the custom variable is not defined.

Example

function checkIfAdKitReady(event) {
    adkit.onReady(getCustomVarValue);
}

function getCustomVarValue() {
    // This example will retrieve the value of a custom variable called mdPanelWidth
    console.log(EB.getCustomVar("mdPanelWidth"));
}

window.addEventListener('load', checkIfAdKitReady);

EB.setCustomVar

Sets a custom variable. It can either override the current value or only set it when the value does not exist.

Code Syntax

EB.setCustomVar(var_name, value, override)

Parameters

Name

Type

Description

var_name

String

Name of the custom variable to set.

value

Optional

  • String

  • Number

  • Array

  • Object

Value to write to the custom variable.

override

Optional | Boolean

Determines whether existing values should be overwritten. Default is false.

Example

function checkIfAdKitReady(event) {
    adkit.onReady(setCustomVarValue);
}

function setCustomVarValue() {
    // This example will set the value of a custom variable called mdCloseButtonShow to false overriding the current value if present
    EB.setCustomVar("mdCloseButtonShow", false, true);
}

window.addEventListener('load', checkIfAdKitReady);

EB.getElementMetrics

Returns an object with detailed information about the size and position of an element.

Note

Note: The viewport-relative and page-relative numbers will be the same inside the creative iFrame.

Code Syntax

EB.getElementMetrics(element)

Parameters

Name

Type

Description

element

HTML element or ID as String

HTML element reference or the ID of an element as a string.

Return Object

Name

Type

Description

width

Number

Page width property.

height

Number

Page height property.

viewPortRelative

Object

(top, bottom, left, right) Distance from the top of the viewport to the top, bottom-side of the element, or left of the viewport to the left, right-side of the element.

pageRelative

Object

(top,bottom, left, right} Distance from the top of the page to the top, bottom-side of the element, or left of the page to the left, right-side of the element.

Example

function checkIfAdKitReady(event) {
    adkit.onReady(getMetrics);
}

function getMetrics() {
    // This example will print in the console the page and viewport relative position of a div called "adContainer"
    console.log(EB.getElementMetrics("adContainer"));
}

window.addEventListener('load', checkIfAdKitReady);

EB.getHighestZIndex

Returns the highest number usable as a z-index by all browsers (except Firefox 2 and Safari 3). Some browsers can go higher, but this is the highest number that all browsers can use.

Code Syntax

EB.getHighestZIndex()

Example

function checkIfAdKitReady(event) {
    adkit.onReady(getMaxZIndex);
}

function getMaxZIndex() {
    // This example will print in the console the highest number that all browsers can use 2147483647
    console.log(EB.getHighestZIndex());
}

window.addEventListener('load', checkIfAdKitReady);

EB.inject

Injects an element to the DOM, according to the specified JSON object that represents the element attributes/children, using the specified method (injectionMethod) and using the specified element (refElem) as reference. The function returns the new created element.

Code Syntax

EB.inject(object, injectionMethod, refElem)

Parameters

Name

Type

Description

object

Object

Object that represents the hierarchy of HTML elements for which we build the tags.

Structure: {tagName:string, [attributes:{name1:value1, ... , style:{name2:value2}}], [children:{}]}

injectionMethod

String

Describes where, in relation to the refElem, the new element should be injected. Acceptable values include:

  • EBG.Adaptors.InjectionMethod.INSERT_BEFORE

  • EBG.Adaptors.InjectionMethod.INSERT_AFTER

  • EBG.Adaptors.InjectionMethod.FIRST_CHILD

  • EBG.Adaptors.InjectionMethod.LAST_CHILD

  • EBG.Adaptors.InjectionMethod.APPEND

refElem

HTML Element

DOM element relative to which the injection is done.

Example

function checkIfAdKitReady(event) {
    adkit.onReady(addElement);
}

function addElement() {
    //This example will add a div to the page and append it to a div with an id "adContainer"
    var tag = {
        tagName: "div",
        attributes: {
            dir: "ltr",
            id: "newDivTag",
            style: {
                display: "inline",
                position: "absolute",
                width: "100%"
            }
        },
        children: [{
            tagName: "iframe",
            attributes: {
                allowfullscreen: true,
                height: 1,
                id: "newIframeTag",
                style: {
                    width: "1px",
                    height: "1px"
                }
            }
        }]
    };
    var el = document.getElementById("adContainer");
    EB.inject(tag, EBG.Adaptors.InjectionMethod.APPEND, el);
}

window.addEventListener('load', checkIfAdKitReady);

EB.getPositioningByElement

Retrieves the top-left coordinate for the element. Position is relative to the creative iFrame window. The function returns an object with X and Y as parameters.

Code Syntax

EB.getPositioningByElement(element)

Parameters

Name

Type

Description

element

HTML Element

HTML Element reference of an element.

Example

function checkIfAdKitReady(event) {
    adkit.onReady(getPosition);
}

function getPosition() {
    // This example will print and object with x and y properties for the element with id 'adContainer'    // e.g. {X:300,Y:-32}
    var element = document.getElementById('adContainer');
    console.log(EB.getPositioningByElement(element));
}
window.addEventListener('load', checkIfAdKitReady);

EB.getPositioningById

Retrieves top-left coordinate for the element with the provided ID. Position is relative to the creative iFrame window. The function returns an object with X and Y as parameters.

Code Syntax

EB.getPositioningByElement(id)

Parameters

Name

Type

Description

id

ID as String

ID of an element.

Example

function checkIfAdKitReady(event) {
    adkit.onReady(getPosition);
}

function getPosition() {
    // This example will print and object with x and y properties for the element with id 'adContainer'    // e.g. {X:300,Y:-32}
    console.log(EB.getPositioningByElement('adContainer'));
}

window.addEventListener('load', checkIfAdKitReady);

EB.removeElement

Removes an element from the page or DOM.

Code Syntax

EB.removeElement(id)

Parameters

Name

Type

Description

id

ID as String

ID of an element to be removed.

Example

function checkIfAdKitReady(event) {
    adkit.onReady(deleteElement);
}

function deleteElement() {
    // This example will remove an element from the DOM called 'adContainer'
    EB.removeElement('adContainer');
}
window.addEventListener('load', checkIfAdKitReady);

EB.getScreenOrientation

Determines the orientation of the creative iFrame window (not the parent page window), either portrait (tall) or landscape (wide) aspect ratio. The function returns a string with PORTRAIT or LANDSCAPE, depending on the creative iFrame.

Code Syntax

EB.getScreenOrientation()

Example

function checkIfAdKitReady(event) {
    adkit.onReady(getOrientation);
}
function getOrientation() {
    // This example will print and string with the word PORTRAIT or LANDSCAPE
    console.log(EB.getOrientation());
}
window.addEventListener('load', checkIfAdKitReady);

EB.getStyle

This method gets a specific style property of a DOM element. The function returns a string with the value of the requested style.

Code Syntax

EB.getStyle(element, style, inline)

Parameters

Name

Type

Description

element

HTML Element

Element from which to read the style.

style

String

Name of the style property to return.

inline

Boolean

Determines whether to return the inline style of the element, the computed style of the class, or the inherited/cascaded style from the element.

Example

function checkIfAdKitReady(event) {
    adkit.onReady(getElementStyle);
}
function getElementStyle() {
    // This example will print in the console the position style (e.g. "absolute") of the adContainer element.
    var element = document.getElementById('adContainer');
    console.log(EB.getStyle(element, "position", false));
}
window.addEventListener('load', checkIfAdKitReady);

EB.setStyle

This method gets a specific style property of a DOM element. The function will return an string with the value of the requested style.

Code Syntax

EB.setStyle(element, style, usePrefix)

Parameters

Name

Type

Description

element

HTML Element

Element from which to read the style.

style

Object

Object that describes the style to apply to the element, for example {width: '100px', height: '50px'}.

inline

Boolean

Default value is true. Determines whether to try to use a vendor-prefixed property, if the browser does not support the requested property.

Example

function checkIfAdKitReady(event) {
    adkit.onReady(setElementStyle);
}
function getElementStyle() {
    // This example will assign a width and height style to the element adContainer
    var element = document.getElementById('adContainer');
    EB.setStyle(element, {width: '300px', height: '50px'}, false);
}
window.addEventListener('load', checkIfAdKitReady);

EB.setStyleToElems

Similar to EB.setStyle, but allows you to pass an array of elements to set the same style.

Code Syntax

EB.setStyleToElems(elements, style, usePrefix)

Parameters

Name

Type

Description

element

HTML Element or array of HTML Elements

Element or elements to which the style is set.

style

Object

Object that describes the style to apply to the element or elements, for example {width: '100px', height: '50px'}.

inline

Optional | Boolean

Default value is true. Determines whether to try to use a vendor-prefixed property, if the browser does not support the requested property.

Example

function checkIfAdKitReady(event) {
    adkit.onReady(setElementsStyle);
}
function setElementsStyle() {
    // This example will assign a width and height style to the element adContainer and video
    var element1 = document.getElementById('adContainer');
    var element2 = document.getElementById('video');
    EB.setStyleToElems([element1, element2], {width: '300px', height: '50px'}, false);
}
window.addEventListener('load', checkIfAdKitReady);

EB.getViewPortMetrics

Retrieves the width and height of the creative iFrame. Note that inside the iFrame, viewport size, page size, and window size are all the same. The function returns an object with Height and Width (also contains the same properties in lowercase as width and height).

Code Syntax

EB.getViewPortMetrics()

Example

function checkIfAdKitReady(event) {
    adkit.onReady(getMetrics);
}
function getMetrics() {
    // This example will print in the console the view port metrics.
    console.log(EB.getViewPortMetrics());
}
window.addEventListener('load', checkIfAdKitReady);

EB.willCloseAdParts

Indicates whether a specific custom interaction has been configured to close ad parts (collapse all panels). The function returns True or False, depending on the given setup for the interaction. If an incorrect argument is passed, the function returns null.

Code Syntax

EB.willCloseAdParts(interaction_name)

Parameters

Name

Type

Description

interaction_name

String

Name of the custom interaction for which to return a value.

If blank, the value for click-through (_eyeblaster) will be returned. Case sensitive.

Example

function checkIfAdKitReady(event) {
    adkit.onReady(willClose);
}
function willClose() {
    // This example will print in the console true or false depending on the given setup for the interaction called 'myInteraction'  
  console.log(EB.willCloseAdParts('myInteraction'));
}
window.addEventListener('load', checkIfAdKitReady);
Was this article helpful?
1 out of 1 found this helpful
Have more questions? Submit a request

Comments