PRODUCT
Follow

Overview

API Extension (called EBAPI) is a module that provides additional functionality to the EB object.

Loading the EBAPI Module 

To load the EBAPI module, add it to the EBModulesToLoad array in the index.html file. 

EBModulesToLoad = ['EBAPI'];

The EBModulesToLoad code should be added to the section of your HTML before any reference to EBLoader or AdKit. For more information, see HOW TO: Load and Initialize the API.

EBAPI Methods 

EB.getAdData()

Description

Gets a variety of properties of a specific ad. Since ad properties are changed over time, rerunning this function will return most updated properties. It mostly retrives information from the adConfig, but also from other areas within the EB istelf.

Code Syntax 
EB.getAdData(properties) 
Parameters
Name  Type  Description 
properties Array List of predefined properties keys.
Return Value
Type  Description 
Object Object containing requested data.
Example

var didUserAlreadyClickthrough = EB.getAdData(["isClickOccur"]).isClickOccur;

var servingData = EB.getAdData(["adId", "placementId", "campaignId"]);
console.log("ad ID  is:", servingData.adId, ", campaign ID is:", servingData.campaignId);

if (EBG.eventName.EXPAND in EB.getAdData(["subscriptions"]).subscriptions) {
     //something subscribed to the EXPAND event
}

EB.setAdData()

Description

Sets a variety of properties for the ad. Similar to EB.getAdData but for writing instead of reading.

Code Syntax 
EB.setAdData(properties) 
Parameters
Name  Type  Parameter Type  Description 
properties Object PATH Name and value that defines the property.
Return Value
Type  Description 
Object Empty if all requested properties had their value updated as required. Any that failed will be listed inside as {propertyName: failReason}.
Example

// Save or change data to the ad object.
EB.setAdData({myName:"customData"});

EB.clip()

Description

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

Code Syntax 
EB.clip(elem, top, right, bottom, left) 
Parameters
Name  Type  Description 
elem  HTMLElement Element to clip.
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. 
Return Value

None/Undefined.

Example

//Clips an element called banner.
var banner = document.getElementById("banner");
EB.clip(banner,0,300,50,0);

EB.unclip()

Description

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

Code Syntax 
EB.unclip(elem) 
Parameters
Name  Type  Description 
element  HTMLElement Element from which to remove clip.
Return Value

None/Undefined.

Example

// Unclips an element called banner.
var banner = document.getElementById("banner");
EB.unclip(banner);

EB.getClipTag()

Description

Generates a string, in the correct format, to be applied to the CSS "clip" property.

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. 
Return Value
Type  Description 
String CSS "clip" string, for example rect(0px 300px 250px 0px).
Example

// Get the correct clipping syntax and assign it to an element. 
var myClip = EB.getClipTag(0, 300, 50, 0);
// returns "rect(50px 50px 50px 50px)"
document.getElementById("banner").style.clip = myClip; 

EB.hasClass() 

Description

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

Code Syntax 
EB.hasClass(elems, classNames, requireAll) 
Parameters
Name  Type  Description 
elems HTMLElement | string | array Elements from which to remove the class. You can supply the HTMLElement, its ID, or an array of HTMLElement and/or IDs.
classNames String | Array Classes to search for from the elements. You can supply a single string or an array of strings. 
requireAll Boolean (Optional) Determines whether to check if ALL the submitted elements to have the submitted classes, or if ANY of them have submitted classes. Default is true.
Return Value
Type  Description 
Boolean True/False
Example

var hasClass = EB.hasClass("banner", "notVisible", false);
if(hasClass){
EB.setClass("banner","isVisible",false);
}

EB.setClass ()

Description

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

Code Syntax 
EB.setClass (elems, classNames, shouldReplace) 
Parameters
Name  Type  Description 
elems HTMLElement | string | array Elements to which the class is applied. You can supply the HTMLElement, its ID, or an array of HTMLElements and/or IDs.
classNames String | Array Classes to apply to the elements. You can supply a single string or an array of strings.  
shouldReplace Boolean (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. 
Return Value

None/Undefined.

Example

var hasClass = EB.hasClass("banner", "notVisible", false);
if(hasClass){
EB.setClass("banner","isVisible",false);
}

EB.removeClass()

Description

Removes a class attribute from an HTML element.

Note: Extra whitespace in the elements' className will be removed.

Code Syntax 
EB.removeClass(elems, classNames) 
Parameters
Name  Type  Description 
elems HTMLElement | string | array Elements from which to remove the class. You can supply the HTMLElement, its ID, or an array of HTMLElement and/or IDs.
classNames String | Array Classes to remove from the elements. You can supply a single string or an array of strings. 
Return Value

None/Undefined.

Example

EB.removeClass("banner", "notVisible");

EB.getCustomVar()

Description

Retrieve the current value of a custom variable from the ad. Custom variables can be defined in the ad at runtime or in Sizmek Advertising Suite beforehand. For a list of name of the custom variables, see the the Custom Variable Definitions in the build guides (for example - Custom Variable Definitions). DW: Jeff - is this explanation ok?

Code Syntax 
EB.getCustomVar(varName, def) 
Parameters
Name  Type  Parameter Type  Description 
varName String Path  Name of the custom variable that you want to retieve.
def String | Number | Array | Object   (Optional) Default value to be returned if the custom variable is not defined. 
Return Value
Type  Description 
String | Number | Boolean | undefined Value of the custom variable.
Examples

Assuming your ad has a custom variable named mdPanelWidth with a value of 600:


var myWidth1 = EB.getCustomVar("mdPanelWidth");           // "600"
var myWidth2 = EB.getCustomVar("mdPanelWidth", "100");    // "600" - Default value has no effect because the value was already defined.

Assuming your ad has a custom variable named mdAutoSnapType that has no predefined value:


var mySnap1 = EB.getCustomVar("mdAutoSnapType", 2);         // 2
var mySnap2 = EB.getCustomVar("mdAutoSnapType");            // undefined

EB.setCustomVar()

Description

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

Code Syntax 
EB.setCustomVar(varName, value, override) 
Parameters
Name  Type  Parameter Type  Description 
varName String Path  Name of the custom variable that you want to set.
value String | Number | Array | Object   Value to write to the custom variable.
override boolean   (Optional) Determines whether existing values should be overwritten. Default is false.
Return Value

None/Undefined.

Examples

Assuming your ad has a custom variable named mdCloseButtonShow with a value of true:


EB.setCustomVar("mdCloseButtonShow", false);        //  Does nothing because default value was already set to true.
var show = EB.getCustomVar("mdCloseButtonShow");    // true

EB.setCustomVar("mdCloseButtonShow", false, true);  //  Use the override.
var show = EB.getCustomVar("mdCloseButtonShow");    // false

EB.getElementMetrics()

Description

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

Note: Typically, the viewport-relative and page-relative numbers will be the same inside the creative iFrame. The function is intended to mimic a similar function available to custom scripts running on the outside of the creative, so uses the same syntax.)

Code Syntax 
EB.getElementMetrics(element) 
Parameters
Name Type  Description 
HTML element HTMLElement or String HTML Element reference or the ID of an element as a string.
Return Value
Type  Description 
Object Object with the following properties:
  • width [number]: Page width property
  • height [number]: Page height property
  • viewPortRelative [object]: Container for viewport-relative positioning info
  • viewPortRelative.top [number]: Distance from top of viewport to top of element
  • viewPortRelative.bottom [number]: Distance from top of viewport to bottom of element
  • viewPortRelative.left [number]: Distance from left of viewport to left of element
  • viewPortRelative.right [number]: Distance from left of viewport to right of element
  • pageRelative [object]: Container for page-relative positioning info
  • pageRelative.top [number]: Distance from top of page to top of element
  • pageRelative.bottom [number]: Distance from top of page to bottom of element
  • pageRelative.left [number]: Distance from left of page to left of element
  • pageRelative.right [number]: Distance from left of page to right of element
Example

// get the page relative and viewport relative position of the "adContainer" element

var metrics = EB.getElementMetrics("adContainer");
var pageRelativeLeft = metrics.pageRelative.left;
var viewPortRelativeLeft = metrics.viewPortRelative.left;

EB.getHighestZIndex()

Description

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.

Return Value
Type  Description 
Number Number 2147483647
Example

// set element style to highest available z-Index

var element = document.getElementById("closeButton");
element.style.zIndex = EB.getHighestZIndex();

EB.inject()

Description

Injects an element to the DOM, according to the specified JSON object that represents the element attributes/children. The injection is done according to the specified method (injectionMethod) and using the specified element (refElem) as reference.

Code Syntax 
EB.inject(obj, injectionMethod, refElem) 
Parameters
Name  Type  Description 
obj 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(from EBG.Adaptors.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 HTMLElement DOM element relative to which the injection is done.
Return Value
Type  Description 
HTMLElement Newly created element.
Example

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"
			}
		}
	}]
};

//add tag to the page and append it to a div with an id "adContainer"
var el = document.getElementById("adContainer");
EB.inject(tag,EBG.Adaptors.InjectionMethod.APPEND,el);

EB.getPositioningByElement() 

Description

Retrieves top left coordinate (positioning) for the resource. Position is relative to the creative iFrame window.

Code Syntax 
EB.getPositioningByElement(element) 
Parameters
Name  Type  Description 
element HTMLElement Element for which to retrieve positioning.
Return Value
Type  Description 
Object Object with "X" [number] and "Y" [number] properties.
Example

var el = document.getElementById("adContainer");
var elementPosition = EB.getPositioningByElement(el);

// returns Object e.g. {X: 367, Y: -32}

EB.getPositioningById()

Description

Retrieves top left coordinate (positioning) for the resource. Position is relative to the creative iFrame window.

Code Syntax 
EB.getPositioningById(elementId) 
Parameters
Name  Type  Description 
elementId String ID attribute of the element for which to retrieve positioning.
Return Value
Type  Description 
Object Object with "X" [number] and "Y" [number] properties.
Example

var position = EB.getPositioningById("adContainer");

// returns Object e.g. {X: 367, Y: -32}

EB.removeElement()

Description

Removes an element from the page or DOM.

Code Syntax 
EB.removeElement(elementId) 
Parameters
Name  Type  Description 
elementId String ID of the element to remove.
Return Value

None/Undefined.

Example

EB.removeElement("adContainer");

EB.getScreenOrientation()

Description

Determines the orientation of the creative iFrame window (not the parent page window) - either portrait (tall) or landscape (wide) aspect ratio.

Return Value
Type  Description 
string Returns PORTRAIT or LANDSCAPE.

EB.getStyle()

Description

This method gets a specific style property of a DOM element.

Code Syntax 
EB.getStyle(elem, style, inline) 
Parameters
Name  Type  Description 
elem HTMLElement  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.
Return Value
Type  Description 
string Value of the specified style property.
Example

var el = document.getElementById("adContainer");
var style = EB.getStyle(el,"position",false);
// returns the position style (e.g. "absolute") of the adContainer element

EB.setStyle()

Description

Sets the style property of the specified element with given style property object. If the element does not accept a specified style property, the method will try to find a matching browser-prefixed equivalent to set instead. For the prefix-matching to work, use camelCase or InitialCaps property names, not kebab-case.

Code Syntax 
EB.setStyle(elem, style, usePrefix) 
Parameters
Name  Type  Description 
elem HTMLElement  Element to which the style is set.
style Object Object that describes the style to apply to the element, for example {width: "100px", height: "50px"}.
usePrefix Boolean (Optional) Default value is true. Determines whether to try to use a vendor-prefixed property in case the browser does not support the requested property.
Example

// Set width and height style to an element called adContainer.
var el = document.getElementById("adContainer");
EB.setStyle(el, {width: "100px", height: "50px"}, false);

EB.setStyleToElems()

Description

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

Code Syntax 
EB.setStyleToElems(elems, style) 
Parameters
Name  Type  Description 
elem  HTMLElement or Array of HTMLElements  Element to which the style is set.
style Object Object that describes the style to apply to the element, for example {width: "100px", height: "50px"}.
Example

// set the same styles to multiple elements
var el =document.getElementById("adContainer");
var el2 =document.getElementById("video");
EB.setStyleToElems([el, el2],{width:"200px", height:"50px"}, false);

EB.getViewPortMetrics()

Description

Gets the width and height of the creative iFrame. Note that inside the iFrame, viewport size, page size, and window size are all the same.

Return Value
Type  Description 
Object Object with Height and Width properties. (Also contains the same properties in lowercase as width and height.)

EB.willCloseAdParts()

Description

This method tells whether a specific custom interaction has been configured to close ad parts (collapse all panels).

MDX2.0:

Sizmek Advertising Suite:

Code Syntax 
EB.willCloseAdParts(interactionName) 
Parameters
Name  Type  Description 
interactionName String Name of the custom interaction for which to return a value.
If blank, the value for clickthrough (_eyeblaster) will be returned. Case sensitive.
Return Value
Type  Description 
Boolean If invalid argument is passed, method will return null.
Example

//Trigger an animation, but only if the interaction will not close the panel
if (!EB.willCloseAdParts("myInteraction") {
    startMyAnim();
}
Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments