PRODUCT
Follow

The creative API contains methods that you can use in your ad code. The API methods are exposed to the ad on two objects, AdKit and EB, depending on the loader script used to initialize the API. The loader script determines accessibility:

  • When using AdKit, both AdKit and EB are accessible.

  • When using EBLoader, only the EB object is accessible.

For more information, see Load and Initialize the API.

AdKit Methods: Interaction Methods

adkit.clickthrough / adkit.clickThrough

Tracks default and custom click-through interactions. Click-through interactions measure events that click-through to the default URL or the specified URL (in the system or the code).

Note

Note: This method is equivalent to EB.clickthrough().

Code Syntax

adkit.clickthrough(interaction_name,url), adkit.clickThrough(interaction_name,url)

Parameters

Name

Type

Required

Description

interaction_name

String

Optional

Interaction name to be tracked and setup in Sizmek Ad Suite (SAS). Cannot contain blank spaces or special characters

url

String

Optional

URL to open.

Example

function checkIfAdKitReady(event) {
    adkit.onReady(function() {
        document.getElementById('szk-click-btn').addEventListener('click', handleClick);
    }
}
function handleClick() {
    // Default clickthrough with url defined in platform
    adkit.clickthrough();
    // Custom clickthrough named "Customized-Click-1" with url defined in platform
    adkit.clickthrough('Customized-Click-1');
    // Custom clickthrough named "Customized-Click-2" with url defined in code
    adkit.clickthrough('Customized-Click-2', "https://www.sizmek.com");
}

window.addEventListener('load', checkIfAdKitReady);

adkit.customInteraction

Important

Important: This method is still being tested and is not exposed externally.

Tracks a user action and opens a URL, if defined. This type of interaction will not affect the CTR Rate since it is not tracked as a user click-through.

Note

Note: This method is equivalent to EB.userActionCounter().

Code Syntax

adkit.customInteraction(interaction_name,url)

Parameters

Name

Type

Required

Description

interaction_name

String

Optional

Interaction name to be tracked and setup in Sizmek Ad Suite (SAS). Cannot contain blank spaces or special characters

url

String

Optional

URL to open.

Example

function checkIfAdKitReady(event) {
    adkit.onReady(function() {
        document.getElementById('szk-user-btn').addEventListener('click', handleClick);
    }
}

function handleClick() {
    // Custom clickthrough named "Customized-User-Action-1" with no url or url defined in platform
    adkit.customInteraction('Customized-User-Action-1');
    // Custom clickthrough named "Customized-User-Action-2" with url defined in code
    adkit.customInteraction('Customized-User-Action-2', 'https://www.sizmek.com');
}

window.addEventListener('load', checkIfAdKitReady);

adkit.userSwipe

Reports a user swipe event.

Note

Note: This method is equivalent to EB.userSwipe().

Code Syntax

adkit.userSwipe()

Example

// This example uses jQuery to simplify the creation of the swipe event as there is no native event for it in javascript

function checkIfAdKitReady(event) {
    adkit.onReady(function() {
        $(window).on('swipe', handleSwipe);
    }
}

function handleSwipe() {
    adkit.userSwipe();
}

window.addEventListener('load', checkIfAdKitReady);

AdKit Methods: Expandable Methods

adkit.expand

Requests the expansion of an ad panel.

Note

Note: This method is equivalent to EB.expand().

Code Syntax

adkit.expand(expansion_properties_object)

Parameters

Name

Type

Required

Description

expansion_properties_object

Object

Optional

Contains the Expand properties.

If not defined, and the Show single panel at a time is set to false, all panels will expand.

Otherwise, only the default panel will expand.

Parameters of the expansion_properties_object:

Name

Type

Required

Description

panelName

String

Optional

Name of the panel to expand.

actionType

String

Optional

Action initiator type. The options include:

  • adkit.ActionType.USER: User initiated. This is the default value.

  • adkit.ActionType.AUTO: Automatically initiated.

useCustomClose

Boolean

Optional

When using In-App serving, you can determine whether to use the standard MRAID close button or a custom button. The default value is false and shows the standard MRAID close button.

animate

Object

Optional

Sets the animation for the expand action.

Parameters of the animate object:

Name

Type

Required

Description

clip

String

Required

Sets the clip as a string in the CSS.

rect (top, right, bottom, left)

For example: rect(0, 100%, 100%, 0)

opacity

Integer

Required

Sets the opacity in the CSS as an integer.

duration

Integer

Required

Sets the animation duration in milliseconds.

easing

Integer

Required

Sets the animation motion type. The options include:

  • adkit.Animation.Easing.LINEAR

  • adkit.Animation.Easing.EASE_IN

  • adkit.Animation.Easing.EASE_OUT

  • adkit.Animation.Easing.EASE_IN_OUT

init

Object

Required

Defines the animation initial state.

Parameters of the init object:

Name

Type

Required

Description

clip

String

Required

Sets the clip as a string in the CSS.

opacity

Integer

Required

Sets the opacity in the CSS as an integer.

Example

function checkIfAdKitReady(event) {
    adkit.onReady(function() {
        document.getElementById('szk-expand-btn').addEventListener('click', handleExpand);
    }
}

function handleExpand() {
    adkit.expand({
        panelName: "panel_1",
        useCustomClose: false,
        animate: {
            clip: "rect(0, 100%, 100%, 0)",
            duration: 2000,
            easing: adkit.Animation.Easing.EASE_IN,
            opacity: 1,
            init: {
                clip: "rect(0, 100%, 0, 100%)",
                opacity: 0
            }
        }
    });
}

window.addEventListener('load', checkIfAdKitReady);

adkit.collapse

Requests the collapse of an ad panel.

Note

Note: This method is equivalent to EB.collapse().

Code Syntax

adkit.collapse(collapse_properties_object)

Parameters

Name

Type

Required

Description

collapse_properties_object

Object

Optional

Contains the Collapse properties.

If not defined, and the Show single panel at a time is set to false, all panels will collapse.

Parameters of the collapse_properties_object:

Name

Type

Required

Description

panelName

String

Optional

Name of the panel to collapse.

actionType

String

Optional

Action initiator type. The options include:

  • adkit.ActionType.USER: User initiated. This is the default value.

  • adkit.ActionType.AUTO: Automatically initiated.

animate

Object

Optional

Sets the animation for the collapse action.

Parameters of the animate object:

Name

Type

Required

Description

clip

String

Required

Sets the clip as a string in the CSS.

rect (top, right, bottom, left)

For example: rect(0, 100%, 100%, 0)

opacity

Integer

Required

Sets the opacity in the CSS as an integer.

duration

Integer

Required

Sets the animation duration in milliseconds.

easing

Integer

Required

Sets the animation motion type. The options include:

  • adkit.Animation.Easing.LINEAR

  • adkit.Animation.Easing.EASE_IN

  • adkit.Animation.Easing.EASE_OUT

  • adkit.Animation.Easing.EASE_IN_OUT

init

Object

Required

Defines the animation initial state.

Parameters of the init object:

Name

Type

Required

Description

clip

String

Required

Sets the clip as a string in the CSS.

opacity

Integer

Required

Sets the opacity in the CSS as an integer.

Example

function checkIfAdKitReady(event) {
    adkit.onReady(function() {
        document.getElementById('szk-collapse-btn').addEventListener('click', handleCollapse);
    }
}

function handleCollapse() {
    adkit.collapse({
        panelName: "panel_1",
        animate: {
            clip: "rect(0, 100%, 0, 100%)",
            duration: 2000,
            easing: adkit.Animation.Easing.EASE_IN,
            opacity: 0,
            init: {
                clip: "rect(0, 100%, 100%, 0)",
                opacity: 1
            }
        }
    });
}

window.addEventListener('load', checkIfAdKitReady);

adkit.onExpand

Runs any time a panel is expanded in our ad. It can include a callback function as a parameter. which receives an object with the expansion information.

Code Syntax

adkit.onExpand(callback_function)

Parameters

Name

Type

Required

Description

callback_function

Function

Required

Function name to be called when the expansion occurs.

Parameters of the callback_function object:

Name

Type

Required

Description

data.panelName

String

Required

Returns the expanded panel name.

Example

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

function startAnimation() {
    adkit.onExpand(panelExpanded);
}

function panelExpanded(expandInfo){
    // The expandInfo parameter contains the expanded panel name
    var panelExpandedName = expandInfo.data.panelName;
}

window.addEventListener('load', checkIfAdKitReady);

adkit.onCollapse

Runs any time a panel is collapsed in our ad. It can include a callback function as a parameter. which receives an object with the expansion information.

Code Syntax

adkit.onCollapse(callback_function)

Parameters

Name

Type

Required

Description

callback_function

Function

Required

Function name to be called when the collapse occurs.

Parameters of the callback_function object:

Name

Type

Required

Description

data.panelName

String

Required

Returns the collapsed panel name.

Example

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

function startAnimation() {
    adkit.onCollapse(panelCollapsed);
}

function panelCollapsed(collapseInfo){
    // The collapseInfoparameter contains the collapsed panel name
    var panelCollapsedName = collapseInfo.data.panelName;
}

window.addEventListener('load', checkIfAdKitReady);

adkit.showBanner

Shows the ad banner (contracted unit) after being hidden using the adkit.hideBanner() method.

Code Syntax

adkit.showBanner()

Example

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

function startAnimation() {
    // By default, the ad banner unit is visible, this assumes the banner was hidden using the method adkit.hideBanner
    adkit.showBanner();
}

window.addEventListener('load', checkIfAdKitReady);

adkit.hideBanner

Hides the ad banner (contracted unit). The banner resides in the HTML page, but will not be visible.

Code Syntax

adkit.hideBanner()

Example

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

function startAnimation() {
    adkit.hideBanner();
}

window.addEventListener('load', checkIfAdKitReady);

adkit.showPanel

Shows the ad panel after being hidden using the adkit.hidePanel method.

Code Syntax

adkit.showPanel(panel_name)

Parameters

Name

Type

Required

Description

panel_name

String

Required

Name of the panel that you want to show.

Example

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

function startAnimation() {
    // By default, a panel unit is visible after the expansion, this assumes the panel was hidden using the method adkit.hidePanel
    adkit.showPanel("Panel1");
}

window.addEventListener('load', checkIfAdKitReady);

adkit.hidePanel

Hides the ad panel. The panel resides in the HTML page, but will not be visible.

Code Syntax

adkit.hidePanel(panel_name)

Parameters

Name

Type

Required

Description

panel_name

String

Required

Name of the panel that you want to hide.

Example

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

function startAnimation() {
    adkit.hidePanel("Panel1");
}

window.addEventListener('load', checkIfAdKitReady);

AdKit Methods: Utils Methods

adkit.onReady

Calls another function once the creative API is initialized and ready to be used.

Code Syntax

adkit.onReady(callback_function)

Parameters

Name

Type

Required

Description

callback_function

Function

Required

Function name to be called when the API is ready.

Example

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

function startAnimation() {
    // This funcion will be called once the API is ready
}

window.addEventListener('load', checkIfAdKitReady);

adkit.onResize

Used to call another function when the ad dimensions change. This will only be triggered for ad resize, not for browser resize.

Code Syntax

adkit.onResize(callback_function)

Parameters

Name

Type

Required

Description

callback_function

Function

Required

Function name to be called when the ad dimensions change.

Example

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

function startAnimation() {
    adkit.onResize(handleResize);
}

function handleResize(){
    // Adapt the creative to the new dimensions.
}

window.addEventListener('load', checkIfAdKitReady);

adkit.onVisibilityChanged

Used to call another function when the ad visibility state changes. The visibility will be applied to the unit that calls this function. If you use it in a panel, the visibility will apply to that panel.

Code Syntax

adkit.onVisibilityChanged(callback_function)

Parameters

Name

Type

Required

Description

callback_function

Function

Required

Function name to be called when the visibility state changes.

Parameters of the callback_function object:

Name

Type

Required

Description

percentage

Integer

Required

Returns the percentage of the unit visible area.

Example

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

function startAnimation() {
    adkit.onVisibilityChanged(handleVisibilityChanged);
}

function handleVisibilityChanged(visibilityInfo){
    // Here you can do something depending on the visible percentage
    if (visibilityInfo.percentage > 75) {
        // Do something, e.g. play video, start animation,...    }
}

window.addEventListener('load', checkIfAdKitReady);

adkit.select/adkit.$

Retrieves a component by ID. The component needs to be previously defined in the AdKit configuration file (config.js) or in Ad Builder.

Code Syntax

adkit.select(component_id) adkit.$(component_id)

Parameters

Name

Type

Required

Description

component_id

String

Required

ID of the component defined in the AdKit configuration file or in Ad Builder.

Example

var videoComponent1;
var videoComponent2;

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

function startAnimation() {
    videoComponent1 = adkit.$('video1');
    videoComponent2 = adkit.select('video2');
}

window.addEventListener('load', checkIfAdKitReady);

adkit.getComponentsByType

Retrieves all components of a specified type within an array.

Code Syntax

adkit.getComponentsByType(component_type)

Parameters

Name

Type

Required

Description

component_type

String

Required

AdKit component type:

  • adkit-media

  • adkit-video360

Example

var components;

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

function startAnimation() {
    components = adkit.getComponentsByType('adkit-media');
    components.forEach(function(comp) {
        // This example will pause all the adkit-media components in the creative.
        comp.pause();
    });
}

window.addEventListener('load', checkIfAdKitReady);

AdKit Methods: Dynamic Methods

adkit.getSVData

Returns the content of a dynamic field when working on a DCO ad. Dynamic elements are defined within the config.js file of the template. For more information, see Add Dynamic Elements to Your HTML Ads Using a Code Editor.

Code Syntax

adkit.getSVData(svKey)

Parameters

Name

Type

Required

Description

svKey

String

Required

SV key as declared in the SV schema within the AdKit configuration file (config.js ).

Example

var dynamicValue;

function checkIfAdKitReady(event) {
    adkit.onReady(function() {
        dynamicValue = adkit.getSVData('svKey');
    });
}

window.addEventListener('load', checkIfAdKitReady);

adkit.clickedVersion

Triggers a click-through and associates it with a specific catalog version/product in catalog ads.

Code Syntax

adkit.clickedVersion(versionIndex,url)

Parameters

Name

Type

Required

Description

versionIndex

Integer

Required

Catalog version/product index.

url

String

Optional

Click-through URL.

Example

function checkIfAdKitReady(event) {
    adkit.onReady(function() {
        document.getElementById("product1").addEventListener('click',handleProduct1Click);
    });
}

function handleProduct1Click(){
    adkit.clickedVersion(1, "https://www.sizmek.com");
}

window.addEventListener('load', checkIfAdKitReady);

adkit.getVersions

Returns the requested catalog versions/products either as an argument of the callback function or null if the catalog versions/products cannot be acquired.

Code Syntax

adkit.getVersions(startIndex,endIndex,callback_function)

Parameters

Name

Type

Required

Description

startIndex

Integer

Required

Index of the first catalog version/product to acquire.

endIndex

Integer

Required

Index of the last catalog version/product to acquire.

callback_function

Function

Required

Function executed when all the requested catalog versions/products are ready.

Parameters of the callback_function object:

Name

Type

Required

Description

startVersionNum

Integer

Required

Index of the first catalog version/product to acquire.

endVersionNum

Integer

Required

Index of the last catalog version/product to acquire.

If not specified, catalog versions/products count will be used.

versionData

Function

Required

Function executed when all the requested catalog versions/products are ready.

Example

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

function handleVersions(){
    adkit.getVersions(1, 5, function(versions){
        if (versions) {
            for (var i = versions.startVersionNum; i <= versions.endVersionNum; i++) {
                var version = versions.versionData[i];
                var value = version['logo'].value;
            }
        }
    });
}

window.addEventListener('load', checkIfAdKitReady);

adkit.getVersionCount

Returns the number of viable catalog versions/products returned by the ad server.

Code Syntax

adkit.getVersionCount()

Example

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

function handleVersions(){
    var numberOfVersions = adkit.getVersionCount();
}

window.addEventListener('load', checkIfAdKitReady);

adkit.getMinVersions

Returns the value defined for minimum versions to load.

Code Syntax

adkit.getMinVersions()

Example

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

function handleVersions(){
    var minVersionsToLoad = adkit.getMinVersions();
}

window.addEventListener('load', checkIfAdKitReady);

adkit.getVersionDataByKey

Important

Important: This method is still being tested and is not exposed externally.

Returns the smart item object for catalog version/product index and smart item key combination (null if not defined) as an argument of the callback function.

This can be used to retrieve specific smart item data from a specific catalog version/product, rather than the entire catalog version/product.

Code Syntax

adkit.getVersionDataByKey(versionIndex,svKey,callback_function)

Parameters

Name

Type

Required

Description

versionIndex

Integer

Required

Index of the requested version/product.

svKey

String

Required

SV key as declared in the SV schema within the AdKit configuration file (config.js).

callback_function

Function

Required

Function that runs when the smart item is ready.

Example

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

function handleVersions(){
    adkit.getVersionDataByKey(1, 'logo', function(smartItem) {
        if (smartItem) {
            var value = smartItem.value;
        }
    });
}

window.addEventListener('load', checkIfAdKitReady);

EB Methods: Interaction Methods

EB.clickthrough

Tracks default and custom click-through interactions. Click-through interactions measure events that click-through to the default URL or the specified URL (in the system or the code).

Note

Note: This method is equivalent to adkit.clickthrough() and adkit.clickThrough().

Code Syntax

EB.clickthrough(interaction_name,url)

Parameters

Name

Type

Required

Description

interaction_name

String

Optional

Interaction name to be tracked and set up in SAS. Cannot contain blank spaces or special characters,

url

String

Optional

URL to open.

Example

function checkIfAdKitReady(event) {
    adkit.onReady(function() {
        document.getElementById('szk-click-btn').addEventListener('click', handleClick);
    }
}

function handleClick() {
    // Default clickthrough with url defined in platform
    EB.clickthrough();
    // Custom clickthrough named "Customized-Click-1" with url defined in platform
    EB.clickthrough('Customized-Click-1');
    // Custom clickthrough named "Customized-Click-2" with url defined in code
    EB.clickthrough('Customized-Click-2', "https://www.sizmek.com");
}

window.addEventListener('load', checkIfAdKitReady);

EB.userActionCounter

Tracks an user action and opens a URL if defined. This type of interaction will not affect the CTR rate, since it will not be tracked as a user click-through.

Note

Note: This method is equivalent to adkit.customInteraction().

Code Syntax

EB.userActionCounter(interaction_name,url)

Parameters

Name

Type

Required

Description

interaction_name

String

Optional

Interaction name to be tracked and set up in SAS. Cannot contain blank spaces or special characters,

url

String

Optional

URL to open.

Example

function checkIfAdKitReady(event) {
    adkit.onReady(function() {
        document.getElementById('szk-user-btn').addEventListener('click', handleClick);
    }
}

function handleClick() {
    // Custom clickthrough named "Customized-User-Action-1" with no url or url defined in platform 
    EB.userActionCounter('Customized-User-Action-1');
    // Custom clickthrough named "Customized-User-Action-2" with url defined in code
    EB.userActionCounter('Customized-User-Action-2', 'https://www.sizmek.com');
}

window.addEventListener('load', checkIfAdKitReady);

EB.automaticEventCounter

Tracks an automatic event counter custom interaction. Automatic event counter interactions measure ad events that are not triggered by user interactions, like progress points in a video. The method receives the name of the interaction to be tracked.

Code Syntax

EB.automaticEventCounter(interaction_name,url)

Parameters

Name

Type

Required

Description

interaction_name

String

Optional

Interaction name to be tracked and set up in SAS. Cannot contain blank spaces or special characters,

url

String

Optional

URL to open.

Example

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

function startAnimation(){
    // This example will record a interaction when the startAnimation funcion is executed
    EB.automaticEventCounter('Animation_Started');
}

window.addEventListener('load', checkIfAdKitReady);

EB.userSwipe

Reports a user swipe event.

Note

Note: This method is equivalent to adkit.userSwipe().

Code Syntax

EB.userSwipe()

Example

// This example uses jQuery to simplify the creation of the swipe event as there is no native event for it in javascript

function checkIfAdKitReady(event) {
    adkit.onReady(function() {
        $(window).on('swipe', handleSwipe);
    }
}

function handleSwipe() {
    EB.userSwipe();
}

window.addEventListener('load', checkIfAdKitReady);

EB Methods: Expandable Methods

EB.closeAd

Important

Important: This method is still being tested and is not exposed externally.

Collapses all expanded panels that belong to the ad.

Code Syntax

EB.closeAd()

Example

// This example uses jQuery to simplify the creation of the swipe event as there is no native event for it in javascript

function checkIfAdKitReady(event) {
    adkit.onReady(function() {
        // This example will close all panels when this funcion is executed
        EB.closeAd();
    }
}

window.addEventListener('load', checkIfAdKitReady);

EB.expand

Request the expansion of an ad panel according to the parameters that were specified in initExpansionParams()/setExpansionParams(), or according to the optional specified expansionParams.

Note

Note: This method is equivalent to adkit.expand().

Code Syntax

EB.expand(expansion_properties_object, auto_collapse)

Parameters

Name

Type

Required

Description

expansion_properties_object

Object

Optional

Relative path to the video asset that stopped playing.

Parameters of the expansion_properties_object object:

Name

Type

Required

Description

panelName

String

Optional

Name of the panel to expand.

If not defined, and the Show single panel at a time is set to false, all panels will expand.

Otherwise, only the default panel will expand.

actionType

String

Optional

Action initiator type. The options include:

  • EBG.ActionType.USER: User initiated. This is the default value.

  • EBG.ActionType.AUTO: Automatically initiated.

autoCollapse

Number

Optional

Indicates (in milliseconds) when the panel should collapse automatically after expanding. It only works for Expandable Banner and not Single Expandable ad formats.

x

Number

Optional

The left offset (x-coordinate) of the collapsed-state rectangle relative to the expanded-state rectangle.

y

Number

Optional

The top offset (y-coordinate) of the collapsed-state rectangle relative to the expanded-state rectangle.

width

Number

Optional

Width of the expanded state rectangle.

height

Number

Optional

Height of the expanded state rectangle.

Example

function checkIfAdKitReady(event) {
    adkit.onReady(function() {
        document.getElementById('szk-expand-btn').addEventListener('click', handleExpand);
    }
}

function handleExpand() {
    // This example will expand the panel called 'panel_1' as user initiated and will auto collapse after 10 seconds
    EB.expand({
        panelName: "panel_1",
        actionType: EBG.ActionType.USER,
        autoCollapse: 10000
    });
}

window.addEventListener('load', checkIfAdKitReady);

EB.collapse

Sends a request to collapse the creative. If the ad format is Expandable Banner, this request removes a panel from the page. If the ad format is Single Expandable, the creative is resized according to the parameters specified in a prior call to initExpansionParams()/setExpansionParams().

Note

Note: This method is equivalent to adkit.collapse().

EB.dispose

Dispose and close the ad, allowing any final actions regarding ad serving to occur.

EB.hideAdPart

Allows hiding ad elements by setting visibility to hidden. If no options are passed, the target element is the banner.

Code Syntax

EB.hideAdPart()

Parameters

Name

Type

Required

Description

options

Object

Optional

Object with properties adPart [EBG.adParts] and panelName.

  • To specify banner: { adPart: EBG.adParts.BANNER }

  • To specify the default panel: { adPart: EBG.adParts.PANEL }

  • To specify a different panel: { adPart: EBG.adParts.PANEL, panelName: "panel1" }

EB.showAdPart

Expose an ad part (by setting visibility to visible) after EB.hideAdPart() was called. If no options are passed, the target element is the banner.

Code Syntax

EB.showAdPart()

Parameters

Name

Type

Required

Description

options

Object

Optional

Object with properties adPart [EBG.adParts] and panelName.

  • To specify banner: { adPart: EBG.adParts.BANNER }

  • To specify the default panel: { adPart: EBG.adParts.PANEL }

  • To specify a different panel: { adPart: EBG.adParts.PANEL, panelName: "panel1" }

EB.isAutoExpandEnabled

Returns a Boolean value that indicates whether the expandable ad was configured (in SAS) to auto-expand. In local mode, there is no configuration information from SAS, so this method will always return true.

Code Syntax

EB.isAutoExpandEnabled()

EB.resetCollapseTimer

Sets or resets a timer to auto-collapse a panel after a specified number of milliseconds. Normally, you would define an auto-collapse by using one of the options given in the parameters to the EB.expand({...}) command, but you can also use resetCollapseTimer to do it. This method can be called from the panel which will be auto-collapsed, from any other panel, or from the banner.

Code Syntax

EB.resetCollapseTimer (panelName, resetTo)

Parameters

Name

Type

Required

Description

panelName

String

Optional

Name of the panel for which the auto-collapse timer will be modified. If not supplied, undefined, or empty, and if the command came from a panel, that will be the panel chosen for the auto-collapse. If the command came from the banner, the default panel will be chosen.

resetTo

Number

Mandatory

Number of milliseconds to reset the collapse timer.

EB.cancelCollapseTimer

Cancels an auto-collapse timer for a panel that was previous set by the EB.resetCollpaseTimer or EB.expand methods. This method can be called from the panel which will be auto-collapsed, from any other panel, or even from the banner.

Code Syntax

EB.cancelCollapseTimer (panelName)

Parameters

Name

Type

Required

Description

panelName

String

Optional

Name of the panel for which the auto-collapse timer will be modified. If not supplied, undefined, or empty, and if the command came from a panel, that will be the panel chosen for the auto-collapse. If the command came from the banner, the default panel will be chosen.

EB.initExpansionParams

Initializes the expansion parameters prior to using expand() and collapse(). If used, this must be called in the main HTML file of the Workspace and not in any external JavaScript.

Note

Notes:

  • This function does not actually have any effect during runtime, but it is mandatory to call it from the ad’s main HTML file since it is scanned by SAS for the initial positioning of the ad.

  • This applies to Single Expandable and related ad formats only; it does not affect Expandable Banner and related formats.

Code Syntax

EB.initExpansionParams(x, y, width, height)

Parameters

Name

Type

Required

Description

x

Number

Required

The left offset (x-coordinate) of the collapsed-state rectangle relative to the expanded-state rectangle.

y

Number

Required

The top offset (y-coordinate) of the collapsed-state rectangle relative to the expanded-state rectangle.

width

Number

Required

Width of the expanded state rectangle.

height

Number

Required

Height of the expanded state rectangle.

Example

function onInit() { EB.initExpansionParams(0, 0, 300, 350); }

By default, the banner expands downwards. You can change the expansion direction as shown in these examples:

For a 728x90 pixel banner expanding to a 728x200 pixel panel:

  • Expand Down: EB.initExpansionParams(0,0,728,200);

  • Expand Up: EB.initExpansionParams(0,110,728,200);

EB.setExpansionParams

Changes the expansion parameters at runtime. The parameters take effect the next time expand() and collapse() are used.

Code Syntax

EB.setExpansionParams(x, y, width, height)

Parameters

Name

Type

Required

Description

x

Number

Required

The left offset (x-coordinate) of the collapsed-state rectangle relative to the expanded-state rectangle.

y

Number

Required

The top offset (y-coordinate) of the collapsed-state rectangle relative to the expanded-state rectangle.

width

Number

Required

Width of the expanded state rectangle.

height

Number

Required

Height of the expanded state rectangle.

Example

EB.setExpansionParams(0, 0, 300, 350);

EB Methods: Utils Methods

EB.addEventListener

Adds a listener for an event and specifies a callback handler.

Code Syntax

adkit.addEventListener(eventName,callback_function,callback_binding)

Parameters

Name

Type

Required

Description

eventName

Integer

Required

Name of the event for which the method is listening. Accepts different arguments depending on which additional modules are loaded. To view a list of events, see Events.

callback_function

Function

Required

Function called when the event is dispatched.

callback_binding

Object

Optional

Object that will be bound to object this when calling the callback function. If no object is specified, the default value is applied. Default value: this.

Example

function onPageLoad() {
    // Here you can do something right after the page was loaded}

EB.addEventListener(EBG.EventName.PAGE_LOAD, onPageLoad);

EB.getSDKData

Important

Important: This method is still being tested and is not exposed externally.

The getSDKData method returns an object with all of the SDK data. Only available when serving in an MRAID-compliant application; otherwise, the value will be null.

EB.browserSupports

Verifies if the browser supports the specified HTML feature using Modernizr. The function will return true or false depending on the browser support for the feature requested.

Code Syntax

EB.browserSupports(feature_name)

Parameters

Name

Type

Required

Description

feature_name

String

Required

Identifies the feature that is being checked. For more information about Modernizr, see Modernizr Documentation.

Example

function checkIfAdKitReady(event) {
    adkit.onReady(function() {
        // This example will print in the console TRUE or FALSE depending on the browser support for canvas.
        console.log(EB.browserSupports('canvas'));
    }
}

window.addEventListener('load', checkIfAdKitReady);

EB.getAssetProps

Returns information about a file in your Workspace. In local mode (before uploading), it will return null.

Code Syntax

EB.getAssetProps (localPath, ebAsset)

Parameters

Name

Type

Required

Description

local_path

String

Required

Path of the file relative to your ad's main index.html.

ebAsset

Number

Optional

Ordinal number of the file, if it is defined as an additional asset.

Response Parameters:

Name

Type

Required

Description

setId

Number

Appears if not null

Unique ID for the asset on SAS servers.

bitRate

Number

Will be -1 where bitRate does not apply.

dsPath

String

Relative path to the asset on SAS display servers (CDN). This is normally all you would need to use for the URL to load the asset. To get a full absolute URL, you should prepend the base URL from theEB.resourcePath [string] property.

enableFS

Number

Indicates whether full-screen should be enabled for the asset. Only relevant for Flash Video.

height

Number

Height of the asset, in pixels, if relevant.

linkedAssets

Null

Deprecated.

ordinalNum

Number

Index number of the file in the Additional Assets list. Usually zero for ordinary workspace assets.

type

Number

Returns a number to represent the file type of the asset. The possible return values include:

  • 0: image

  • 26: html

  • 27: javascript

  • 28: webm video

  • 29: ogg video

width

Number

Width of the asset, in pixels, if relevant.

Example

//returns information about index.html file:
var assetProps = EB.getAssetProps("index.html");

// returns information about additional asset 1.
// note: if trying to retrieve information about an additional asset it will override the localpath property.

// In which case one should enter an empty string when trying to get information about additional assets:
var assetProps = EB.getAssetProps("",1);

//Get the width and height of the asset:
var assetWidth = assetProps.width;
var assetHeight = assetProps.height;

EB.getAssetUrl

Returns the URL of a valid asset file. Returns "" if the asset was not located. When using a path to refer to assets using EB.getAssetUrl, the path is always relative to the main (root) folder. This means that if EB.getAssetUrl is invoked from the banner or from one of the panels, the path for assets is relative to the root folder, not the folder where the current HTML file resides.

For example: If there is a folder named assets under the root folder, with a video named myVideo.ogg in it, that asset is always accessed using EB.getAssetUrl('assets/myVideo.ogg', 1);

Code Syntax

EB.getAssetUrl(asset, additionalAsset)

Parameters

Name

Type

Required

Description

asset

String

Required

Ordinal number, file name, or URL of the asset to search for in urlParams.

additionalAsset

Integer

Optional

Number of the additional asset as it was defined in SAS (for example, ebMovie1).

Example

EB.getAssetUrl('FolderName\\video.webm', 1)

EB.getDimensions

Returns the original dimensions of the banner, as designed. In the case of an In-Stream, adaptive, or responsive ad, this may not match the current dimensions if the creative has been resized. When this function is called from within an expandable panel, it returns the dimensions of the banner, not the panel.

Code Syntax

EB.getDimensions()

Parameters

Response Parameters:

Name

Type

Required

Description

width

Number

Required

Width dimension.

height

Number

Required

Height dimension.

EB.getVisibilityData

Returns information about the viewability status of the ad (or panel if called from a panel in an expandable ad). The object returned will always have an available property. If viewability data is not available, this property will be false and the object will have no other properties. If the collection of viewability data is enabled for the ad, this property will be true.

If viewability is enabled and the initial scan of viewability has completed, the object will also contain additional properties that describe the viewability status. If you get {available: true} and no other properties, you need to wait (a few milliseconds) before trying again, so the viewability scan has time to complete.

Code Syntax

EB.getVisibilityData()

Response Parameters

Name

Type

Required

Description

available

Boolean

Always present

Determines whether viewability data is being scanned or collected for this asset.

assetId

String

Optional

Unique ID for the asset (banner or panel) on the page.

customData

Object

Optional

Miscellaneous data, usually only used by custom formats.

percentage

Number

Optional

Percentage of the asset that is within the veiwport.

viewport

Object

Optional

Object with width [number] and height [number] properties.

visibleRect

Object

Optional

An object with the same structure as a DOMRect, describing a rectangle that is the portion of the asset that is within the viewport. Positioning coordinates are relative to the top left corner of the viewport. Contains the following properties:

  • top

  • left

  • bottom

  • right

  • width

  • height

Example

// Check the visibility percentage of the ad when the window is resized or scrolled. 
//If the ad is 80% visible or higher play the video. 
// If the ad is below 80% visible then pause the video. window.addEventListener("resize", checkVisibilityState);
window.addEventListener("scroll", checkVisibilityState);

function checkVisibilityState(event) {
    var visibility = EB.getVisibilityData();
    var video = document.getElementBy("video");
    if (visibility.percentage >= 80) {
        video.play();
    } else {
        video.pause();
    }
};

EB.notifyMessage

This method sends arbitrary data to the EBG object outside the creative iFrame. This function is useful for custom formats, or other ads that have a custom script attached, that listen for such messages.

Code Syntax

EB.notifyMessage( {name: "myMessage"} );

Parameters

Name

Type

Required

Description

Object Name

Object

Required

Object with any data that can be converted to a string. This object must also have a .name property, which should have a string value.

Example

EB.notifyMessage({
    name: "myMessage"
});
EB.notifyMessage({
    name: "myMessageWithData",
    data: {
        abc: 123
    }
});
EB.notifyMessage({
    name: "myOtherMessage",
    bits: 123,
    pieces: "abc",
    foo: {
        bar: "baz"
    }
});

EB.isMobileDevice

Uses a user-agent to determine if the client is a mobile device.

Code Syntax

EB.isMobileDevice()

Return Response

Returns true/false Boolean value.

EB.relativeToAbsolute

Translates a relative URL into an absolute URL. The Base URL that is used will be the ad Workspace's address on the SAS CDN. This function is useful for referring to Workspace assets when served in an environment that does not support relative URLs.

Code Syntax

myImage.src = EB.relativeToAbsolute("images/myImage.png");

Parameters

Name

Type

Required

Description

path

String

Required

Workspace asset path.

Example

myImage.src = EB.relativeToAbsolute("images/background.jpg");

/*This will return the absolute URL path. (An absolute or full path points to the same location in a file system, regardless of the current working directory.) 
For example: http://ds.serving-sys.com/resources/PROD/html5/45884/20180214/1074179787/34915138550104464/panels/default/images/background.jpg
*/

EB.removeEventListener

Remove the specified listener (subscription) from the specified event.

Code Syntax

EB.removeEventListener (subscription)

Parameters

Name

Type

Required

Description

subscription

Object

Required

Subscription object. This object was the return value from EB.addEventListener().

Example

myImage.src = EB.relativeToAbsolute("images/background.jpg");

/*This will return the absolute URL path. (An absolute or full path points to the same location in a file system, regardless of the current working directory.) 
For example: 
http://ds.serving-sys.com/resources/PROD/html5/45884/20180214/1074179787/34915138550104464/panels/default/images/background.jpg
*/

EB.showDefaultImage

Makes a request to show the default image defined for the ad, instead of the displayed rich banner.

Code Syntax

EB.showDefaultImage()

Example

if (!EB.browserSupports('canvas')){    EB.showDefaultImage();}

EB.isInitialized

Checks whether the EB object is fully initialized and available for API calls. The function will return TRUE or FALSE depending on the load status of the EB object.

Code Syntax

EB.isInitialized()

Parameters

Name

Type

Required

Description

asset_path

String

Required

Relative path to the video asset that stopped playing.

Example

function checkIfEBLoaderReady(event) {
    if (!EB.isInitialized()) {
        EB.addEventListener(EBG.EventName.EB_INITIALIZED, startAd);
    } else {
        startAd();
    }
}

function startAd() {
    // This function is executed once the EB Object is available.
}
window.addEventListener("load", checkIfEBLoaderReady);

EB.startTimer

Starts a timer to measure the duration of a custom interaction.

Code Syntax

EB.startTimer(interaction_name)

Parameters

Name

Type

Required

Description

interaction_name

String

Required

Name of the interaction timer.

Example

function checkIfAdKitReady(event) {
    adkit.onReady(function() {
        EB.startTimer('animation_playing');
    }
}

window.addEventListener('load', checkIfAdKitReady);

EB.stopTimer

Stops a timer to measure the duration of a custom interaction.

Code Syntax

EB.stopTimer(interaction_name)

Parameters

Name

Type

Required

Description

interaction_name

String

Required

Name of the interaction timer.

Example

function checkIfAdKitReady(event) {
    adkit.onReady(function() {
        // This example will stop the timer after 5 seconds
        setTimeout(function(){
            EB.stopTimer('animation_playing');
        },5000);
            }
}

window.addEventListener('load', checkIfAdKitReady);

EB Methods: Video Methods

EB.startVideoTimer

Starts a video timer for the specified asset.

Code Syntax

EB.startVideoTimer(asset_path)

Parameters

Name

Type

Required

Description

asset_path

String

Required

Relative path to the video asset that stopped playing.

Example

// This example assumes you have a video element with id 'video01'

var videoElement;

function checkIfAdKitReady(event) {
    adkit.onReady(function() {
        videoElement= document.getElementById("video01");
        videoElement.addEventListener('play',function(){
           EB.startVideoTimer('videos/video01.mp4');
        }
     }
}

window.addEventListener('load', checkIfAdKitReady);

EB.stopVideoTimer

Stops a video timer for the specified asset.

Code Syntax

EB.stopVideoTimer(asset_path)

Parameters

Name

Type

Required

Description

asset_path

String

Required

Relative path to the video asset that stopped playing.

Example

// This example assumes you have a video element with id 'video01'

var videoElement;

function checkIfAdKitReady(event) {
    adkit.onReady(function() {
        videoElement= document.getElementById("video01");
        videoElement.addEventListener('pause',function(){
           EB.stopVideoTimer('videos/video01.mp4');
        }
     }
}

window.addEventListener('load', checkIfAdKitReady);

EB.videoInteraction

Tracks a video interaction for a specified asset.

Code Syntax

EB.videoInteraction(interaction_name, asset_path, isUserInitiated)

Parameters

Name

Type

Required

Description

interaction_name

String

Required

Name of the video interaction.

asset_path

String

Required

Relative path to the video asset that stopped playing.

isUserInitiated

Boolean

Optional

Default is false.

Example

// This example assumes you have a video element with id 'video01'
var videoElement;

function checkIfAdKitReady(event) {
    adkit.onReady(function() {
        videoElement= document.getElementById("video01");
        videoElement.addEventListener('play',function(){
           EB.videoInteraction(EBG.VideoInteraction.USER_INITIATED_VIDEO, "videos/video01.mp4");
        }
     }
}
window.addEventListener('load', checkIfAdKitReady);
Was this article helpful?
1 out of 1 found this helpful
Have more questions? Submit a request

Comments