Overview

Sizmek HTML5 Workspaces is a toolset for programmers to incorporate our HTML5 rich media features using the authoring environment of your choice. Workspaces are ZIP  folders that contain all of the assets and files you’ll need for a single ad, pre-packaged with the Sizmek HTML5 API code. The API code is added to the index.html file in the root of the Workspace and contains the ad’s main creative file and initialization code. For more information, see OVERVIEW: HTML5 Workspaces.

Setting Up the HTML5 API Environment

The API is exposed to the ad creative on an object called “EB”. All the API functions are methods of the EB object. For example, if you want to perform a click-through to a landing page, you can execute the following.EB.clickthrough();

Important: The creative EB declaration was used in the past to initialize the EB object in the HTML5 API. However, the Creative AdKit declaration has replaced the EB loader. For more information, see HOW TO: Load and Initialize the API.

Add the AdKit declaration to the index.html automatically updates the index.html with dynamic AdKit scripts when the ad is served. The AdKit declaration references the EBLoader, while retaining all the existing EBLoader functionality. 

Procedure

• To setup up the HTML5 environment, copy the following script tag to the index.html:
  

  <script type="text/javascript" src="http://ds.serving-sys.com/BurstingScript/adKit/adkit.js"> </script> 

API Methods

The following API methods are available. 

EB.addEventListener()

Description

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

Code Syntax 

EB.addEventListener(eventName, callback, callbackBinding)

Parameters

Example 

function onPageLoad() {
    // do something
} 
// Calls onPageLoad() when the EBG.EventName.PAGE_LOAD event is heard
EB.addEventListener(EBG.EventName.PAGE_LOAD, onPageLoad); 

EBG.EventName.SDK_DATA_CHANGE

Description

The EBG.EventName.SDK_DATA_CHANGE event complies with MRAID and is dispatched each time data changes as a result of an event.

Code Syntax 

EB.addEventListener(EBG.EventName.SDK_DATA_CHANGE,onDataChanged);
function onDataChanged(dataObj){
} 

Parameters

Example

EB.addEventListener(EBG.EventName.SDK_DATA_CHANGE,onDataChanged);
function onDataChanged(event){
    if (event.SDKData.version < 2) {
        //perform mraid 1 functionality
    }
    else {
        //perform mraid 2 functionality
    }
}

EB.getSDKData()

Description

The getSDKData method returns an object with all of the SDK data.

Note: When an ad is not running in an MRAID-compliant application, EB.getSDKData() returns a null value, and the EBG.EventName.SDK_DATA_CHANGE event is not dispatched.

Code Syntax

var SDKData = EB.getSDKData(); 

Parameters

Example

var sdkData = EB.getSDKData();

function initializeCloseButton(sdkData) {
	
// check if the ad is being served in a Mobile APP , EB.getSDKData() will return an object that is not null.
// When served in a mobile app environment we want to use the creative close button and not the APP close button to collapse the panel
	
	if(sdkData !== null) {
		if(sdkData.SDKType === "MRAID") {
			
			// set sdk to use custom close button
			EB.setExpandProperties({
				useCustomClose: true
			});
		}
	}
}
initializeCloseButton(sdkData);

EB.automaticEventcounter()

Description

Tracks an automatic event counter custom interaction. Automatic event counter interactions measure ad timeline vents, like progress points in a video.

The method receives the name of the interaction to be tracked.

Code Syntax

EB.automaticEventCounter(intName, clickURL)

Parameters

Example

// Tracks custom interaction "myAutomaticEventInt"
EB.automaticEventCounter("myAutomaticEventInt"); 

EB.browserSupports()

Description

Verifies if the browser supports the specified HTML feature, using Modernizr. For more information about Modernizr, click here.

Code Syntax

EB.browserSupports(featureName) 

Parameters

Response Parameters

BrowserSupports returns a true/false boolean value.

Response Example

// Shows the default image if the browser supports the <canvas> element
if (!EB.browserSupports('canvas'))
    EB.showDefaultImage();

EB.cancelCollapseTimer()

Description

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, or from any other panel, or even from the banner.

Code Syntax

EB.cancelCollapseTimer (panelName)

Parameters

Example

document.querySelectorAll("button").addEventListener("click", handleButtonClicks);
function handleButtonClicks(event) {
    // cancel auto-collapse upon interaction
    EB.cancelCollapseTimer();
    
    // ...other onClick functionality...
}

EB.clickthrough()

Description

Tracks a clickthrough interaction. Clickthrough interactions measure events that click through to another URL, if defined in the Sizmek platform.
This method receives the name of the interaction to be tracked. If no name is specified, it tracks the main/default click interaction that is defined on the ad level.

Note: Custom Interactions cannot be applied to Standard HTML5 ads.

Code Syntax

EB.clickthrough(intName, clickURL) 

Parameters

Example

// General click interaction using the Clickthrough URL defined in the Sizmek platform//
EB.clickthrough(); 
// Custom click interaction using the Clickthrough URL defined in the Sizmek platform
EB.clickthrough("myClickInteraction"); 
// Custom click interaction specifying the redirect URL
EB.clickthrough("myClickInteraction","http://www.mediamind.com"); 

EB.closeAd()

Description

Collapses all expanded panels that belong to the ad.

Code Syntax

EB.closeAd()

EB.collapse()

Description

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().

Code Syntax

EB.collapse(collapseOptions)

Parameters

Example

//Collapse all panels
EB.collapse();

//Collapse a specific panel
EB.collapse( {panelName: "panel2"} );

//Collapse a specific panel and leave the scrollbars hidden
// (as previously requested)
var collapseParams = {
    panelName: "panel1",
    restoreScrollBarsState: false
};
EB.collapse(collapseParams);

EB.dispose() 

Description

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

EB.hideAdPart()

Description

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

Code Syntax

EB.hideAdPart()

Parameters

Example

// To hide the banner use either 
EB.hideAdPart(); 
 
//or

EB.hideAdPart({ adPart: EBG.adParts.BANNER });

// To hide the default panel:
EB.hideAdPart({ adPart: EBG.adParts.PANEL });

// To hide a specific panel named "bigPanel"
EB.hideAdPart({
    adPart: EBG.adParts.PANEL,
    panelName: "bigPanel"
});

EB.expand()

Description

Sends a request to expand the creative according to the parameters that were specified in initExpansionParams()/setExpansionParams(), or according to the optional specified expansionParams.

Note: If the expansion is not user-initiated, the actionType can be specified in the expandObj parameter.

Code Syntax

EB.expand(expansionParams, autoCollapse)

Parameters

Example

EB.expand();
var expansionParams = {
x: 0,
y: 0,
width: 300,
height: 350,
actionType: EBG.ActionType.AUTO }; EB.expand(expansionParams);

EB.getAssetProps()

Description

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

Code Syntax

EB.getAssetProps (localPath, ebAsset)

Parameters

Returns Response

Returns an object with the following properties:

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() 

Description

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 no matter 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.
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’);

Code Syntax

EB.getAssetUrl(asset:String):String

Parameters

Example

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

EB.getDimensions()

Description

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 is called from within an expandable panel, it returns the dimensions of the banner, not the panel.

Code Syntax

EB.getDimensions()

Returns Response

Returns object with width and height properties.

Example

//returns the dimensions of the banner;

var dimensions = EB.getDimensions();
var width = dimensions.width 
var height = dimensions.height;

EB.getVisibilityData()

Description

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 [boolean] 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 various properties describing the viewability status. If you get {available: true} and no other properties, you need to wait a while (a few milliseconds) before trying again, so the viewabilty scan has time to complete.

Code Syntax

EB.getVisibilityData()

Returns Response

Returns an object with the following properties:

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.initExpansionParams()

Description

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.

Code Syntax

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

Parameters

Example 

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

By default the banner expands downwards. You can change the expansion direction by following the 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.isAutoExpandEnabled()

Description

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

Code Syntax

EB.isAutoExpandEnabled()

Returns Response

Example

//If auto expand is enabled in the platform, disable video auto play on first expansion

var autoExpand =false;

function checkAutoExpansion()
{
	var vid;
	
	If(EB.isAutoExpandEnabled() && !autoExpand)
	{
		autoExpand = true;
		vid = document.getElementById("video");
		vid.autoplay = false;
	}
}

checkAutoExpansion();

EB.isInitialized()

Description

Checks whether the EB object is fully initialized and available for API calls.

Code Syntax

EB.isInitialized()

Returns Response

True if the EB object is fully initialized and available for API calls.

Response Example

function checkInit() {
    if (!EB.isInitialized()) {
        EB.addEventListener(EBG.EventName.EB_INITIALIZED, onInit); 
        // This code checks whether the EB object is initialized, if the object is initialized, it launches the function "onInit", otherwise it registers to the "EB_INITIALIZED" event.
    }
    else {
        onInit()
    }
}

Example

function checkInit() {
    if (!EB.isInitialized()) {
        EB.addEventListener(EBG.EventName.EB_INITIALIZED, onInit); 
        // This code checks whether the EB object is initialized, if the object is initialized, it launches the function "onInit", otherwise it registers to the "EB_INITIALIZED" event.
    }
    else {
        onInit()
    }
}

EB.notifyMessage() 

Description

This is a method for sending 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

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()

Description

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

Response Parameters

Returns true/false boolean value.

EB.relativeToAbsolute()

Description

Translates a relative URL into an absolute URL. The Base URL that is used will be the ad workspace's address on the Sizmek 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

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()

Description

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

Code Syntax

EB.removeEventListener (subscription) 

Parameters

Example

var motionSub = EB.addEventListener(EBG.EventName.DEVICE_MOTION, handleMotion);
function handleMotion(event) {
    // We only want to handle this once, so remove the listener.
    EB.removeEventListener(motionSub);
    
    // Do something related to device motion...
}

EB.resetCollapseTimer()

Description

Sets or resets a timer to auto-collapse a panel after a specified number of milliseconds. Normally, you would define an autoCollapse 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, or from any other panel, or even from the banner.

Code Syntax

EB.resetCollapseTimer (panelName, resetTo)

Parameters

Example

// In the panel, set it to auto-collapse after 5 seconds
EB.resetCollapseTimer(null, 5000);

// In the banner, set the default panel to auto-collapse after 4 seconds
EB.resetCollapseTimer(null, 4000);

// From within any ad-part, set a panel called "mypanel" to auto-collapse after 3 seconds
EB.resetCollapseTimer("mypanel", 3000);

EB.setExpansionParams()

Description

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

Code Syntax

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

Parameters

Example

EB.setExpansionParams(0, 0, 700, 400); 

EB.showAdPart()

Description

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

Code Syntax

EB.showAdPart()

Parameters

Example

// To show the banner use either 
EB.showAdPart()

//or

EB.showAdPart({ adPart: EBG.adParts.BANNER });

// To show the default panel:
EB.showAdPart({ adPart: EBG.adParts.PANEL });

// To show a specific panel named "bigPanel"
EB.showAdPart({
    adPart: EBG.adParts.PANEL,
    panelName: "bigPanel"
});

EB.showDefaultImage()

Description

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.startTimer() 

Description

Starts a timer to measure the duration of a custom interaction. To stop the timer, use stopTimer().

Code Syntax

EB.startTimer(intName)

Parameters

Example

EB.startTimer("myCustomTimerInteraction");

EB.stopTimer()

Description

Stops a timer used to measure the duration of a custom interaction. To start the timer, use startTimer().

Code Syntax

EB.stopTimer(intName)

Parameters

Example

EB.stopTimer("myCustomTimerInteraction");

EB.startVideoTimer()

Description

Starts a video timer for the specified asset. To stop the timer, use stopVideoTimer() .

Code Syntax

EB.startVideoTimer(localPath)

Parameters

Example

EB.startVideoTimer("myVideos/trailer.mpg");

EB.stopVideoTimer()

Description

Stops a video timer for the specified asset. To start the timer, use startVideoTimer().

Code Syntax

EB.stopVideoTimer(localPath)

Parameters

Example

EB.stopVideoTimer("myVideos/trailer.mpg"

Smart Versioning

Description

See HOW TO: Add Smart Versioning Items using the API.

EB.userActionCounter()

Description

Tracks a user action custom interaction. User action counter interactions measure user action events such as clicking on a button or playing with an ad part. The method receives the name of the interaction to be tracked.

Code Syntax

EB.userActionCounter(intName, clickURL)

Parameters

Example

// Tracks custom interaction "myUserActionInteraction" using the Clickthrough URL defined in the Sizmek platformEB.userActionCounter("myUserActionInteraction");
// Tracks custom interaction specifying the redirect URL

/EB.userActionCounter("myUserActionInteraction", "http://www.mediamind.com");

EB.userSwipe

Description

Command the ad to report a "swipe" interaction to our servers.

Code Syntax

EB.userSwipe()

EB.videoInteraction()

Description

Tracks a video interaction for a specified asset.

Code Syntax

videoInteraction(intName, localPath, isUserInitiated)

Parameters

Example

EB.videoInteraction(EBG.VideoInteraction.STARTED, "myVideos/trailer.mpg");