Follow

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 Workspace contains the ad’s main creative file and initialization code, and the API code is added to the index.html file in the root of the Workspace. 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 OVERVIEW: AdKit Loader and EBLoader Comparison.

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
Name Type Description
eventName EBG.EventName Name of the event that is being listened for. Accepts different arguments depending on which additional modules are loaded. To view a list of events, see REFERENCE: HTML5 API Events.

Modules include: 

  • EBG.EventName.EB_INITIALIZED
  • EBG.EventName.DEVICE_MOTION: Dispatched when the devicemotion event is detected in the parent window.
  • EBG.EventName.PAGE_LOAD: Dispatched when any of the following windows finish loading:
    • Topmost accessible parent window
    • Any of the creative iFrames
    • Example banner, panel1, panel2
  • EBG.EventName.SCREEN_ORIENTATION: Dispatched when the screen orientation changes. Only works on mobile devices.
  • EBG.EventName.EXPAND: Dispatched when any expandable panel, that belongs to the ad, is expanded.
  • EBG.EventName.COLLAPSE: Dispatched when any expandable panel, that belongs to the ad, is collapsed.

The following modules are also available when the EBCAT modules have been loaded:

  • EBG.EventName.CATALOG_READY: Dispatched when the catalog data has been loaded from server.
  • EBG.EventName.VERSION_READY: Dispatched when the data for a single version has been loaded from server.
  • EBG.EventName.VERSION_FAILED: Dispatched when the data for a single version failed to load from server.
  • EBG.EventName.CATALOG_FAILED: Dispatched when the catalog data failed to load from server.

The following modules are also available when the EBCMD modules have been loaded:

  • EBG.EventName.collapseAd: Dispatched when MRAID, or another mobile-device in-app container, instructs the ad to collapse.
  • EBG.EventName.expandAd: Dispatched when MRAID, or another mobile-device in-app container, instructs the ad to collapse.
  • EBG.EventName.SDK_DATA_CHANGE: Dispatched when MRAID, or another mobile-device in-app container, instructs the ad to collapse. 
  • EBG.EventName.SDK_EVENT: Dispatched when MRAID, or another mobile-device in-app container, sends a command to the ad.

The following modules are also available when the EBSV modules have been loaded:

  • EBG.EventName.SV_DATA_READY: Dispatched when the version data has been loaded from server.
  • EBG.EventName.VERSION_READY: Dispatched when the version data failed to load from server.
callback function Called when the event is dispatched.
callbackBinding (optional) object Object to bind as this when calling the callback.
Example 
function onPageLoad() {
// do something
} 
// Calls onPageLoad() when the EBG.EventName.PAGE_LOAD event is heard
EB.addEventListener(EBG.EventName.PAGE_LOAD, onPageLoad); 

 

 

 

 
 
 
     
   
 
  •  
    •  
    •  
    •  
    •  
    •  
    •  

EB.getSDKData

Description

The getSDKData method provides a synchronous way to get all the same information as included on the SDK_DATA_CHANGE event without having to wait for an event. It 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(); 
Return Value
  Type  
     
  object
  •  
  • SDKData: The object that contains the SDK data. Sizmek currently supports the following properties:
    • SDKData.version
    • SDKData.SDKType
    • SDKData.placementType
    • SDKData.maxSize: Can change when a sizeChange event is triggered.
    • SDKData.currentPosition: Can change when a sizeChange event is triggered.
    • SDKData.screenSize: Can change when a sizeChange event is triggered. 

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
function automaticEventCounter(intName, clickURL){
Parameters
Name Type Description
intName String Name of the interaction to be tracked.
clickURL (optional) String Click-through URL that should open. If no URL is specified, the URL that is defined in the Sizmek MDX platform for the specified interaction is used instead.
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
function browserSupports(featureName){ 
Parameters
Name Type Description
featureName String A string that is used to identify the feature that is being checked. For example, 'canvas', 'video'.
Return Value

BrowserSupports returns a true/false boolean value.

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
Name Type 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.
Example
// Cancel the auto-collapse timer for a specific panel named "panel2"
EB.cancelCollapseTimer("panel2");

// Cancel the auto-collapse timer for the default panel or current panel
EB.cancelCollapseTimer();

EB.clickthrough()

Description

Tracks a clickthrough interaction. Clickthrough interactions measure events that click through to another URL, if defined in the Sizmek MDX 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.

Syntax
EB.clickthrough([intName[, clickURL]])    --[JB square brackets indicate optional args] 
Parameters
Name Type Description
intName String The name of the interaction to be tracked.

Note: If you are defining the ad's general click interaction, leave this parameter blank or empty to use (EB.Clickthrough).

clickURL (optional) String The clickthrough URL that opens. If no URL is specified, the URL that is defined in the Sizmek MDX platform for the specified interaction is used instead.
Example
// General click interaction using the Clickthrough URL defined in the Sizmek MDX platform//
EB.clickthrough(); 
// Custom click interaction using the Clickthrough URL defined in the Sizmek MDX 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. If you want to completely unload and remove your ad from the page use EB.dispose instead.

Syntax
EB.closeAd();

EB.collapse()

Description

Sends a request to collapse the creative according to the parameters specified in a prior call to initExpansionParams()/setExpansionParams().

Syntax
EB.collapse([collapseParams])
Example
// Collapse the current panel or default panel
EB.collapse();

// Collapse the current panel or default panel, and track it as a 
// non-user-initiated action.
var collapseParams = { actionType: EBG.ActionType.AUTO };
EB.collapse(collapseParams);

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

//Collapse a specific panel named "panel2" and track it as a user-initiated action.
EB.collaspe({
    panelName:"panel1", actionType: EBG.ActionType.USER });

 

 
     
     

EB.dispose()

Description

Dispose and close the ad, allowing any final actions regarding ad serving to occur. If you want to be able to re-expand your ad later, use EB.closeAd instead.

Syntax
EB.dispose();

EB.hideAdPart()

Description

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

Syntax
EB.hideAdPart(options);
Parameters
Name Type Description
options Object (Optional) Object with information about what should be hidden, with properties adPart and (optional) panelName.
  • adPart should be either EBG.adPart.PANEL, or EBG.adPart.BANNER.
  • panelName should be a String
   
  •  
  •  
  •  
Examples
// To hide the banner:
EB.hideAdPart({ adPart: EBG.adPart.BANNER });

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

// To hide a specific panel named "bigPanel"
EB.hideAdPart({
    adPart: EBG.adPart.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.

Syntax
EB.expand([expansionParams])
Parameters
Name Type Description
expansionParams (optional) Object Anobject that contains the expansion parameters and action type:
Parameter Type Description
x Number The left offset (x-coordinate) of the collapsed-state rectangle relative to the expanded-state rectangle.
y Number The top offset (y-coordinate) of the collapsed-state rectangle relative to the expanded-state rectangle.
width Number The width of the expanded-state rectangle.
height Number The height of the expanded-state rectangle
actionType (optional) EBG.ActionType The expansion type of the expansion: EBG.ActionType.USER (if user initiated). This is the default. Or EBG.ActionType EBG.ActionType.AUTO (if automEBG.ActionType automatically initiated)
panelName (optional) String User-defined panel name to be expanded.

You can either configure this field in the code or via the HTML5 Expandable settings in the Platform. For more information, see Build an HTML5 Expandable Ad in the Sizmek MDX Platform.

If this field is not defined in the code, the following GUI Settings are applied:

  • Selecting the Show single panel at a time checkbox, expands the default panel.
  • Selecing the Show Single Panel at a Time  checkbox causes all panels to expand.
autoCollapse (optional) Number Indicates (in milliseconds) when the panel should be automatically collapsed after expanding. It works only for Expandable, not SingleExpandable.

See also  XXX EB.resetCollapseTimer() and EB.cancelCollapseTimer().

 

 

 

 

 

 

 

Example
// expand the default panel
EB.expand();

// expand the default panel, specifying size and position, and 
// tracking it as a non-user-initiated action
var expansionParams = {
    x: 0,
    y: 0,
    width: 300,
    height: 350,
    actionType: EBG.ActionType.AUTO }; EB.expand(expansionParams);

getAssetProps

Description

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

Code Syntax

function getAssetProps (localPath, ebAsset)
Parameters
Name Type Description
localPath String (Optional) Path of the file relative to your ad's main index.html.
ebAsset Number Ordinal number of the file, if it is defined as an additional asset.
Returns Response

Returns an object with the following properties:

Name Type Description
assetID Number Unique ID for the asset on our servers.
bitRate Number Will be -1 where bitRate does not apply.
dsPath String Relative path to the asset on Sizmek display servers (CDN). This is normaly 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
  • 0 = image
  • 26 = html
  • 27 = javascript
  • 28 = webm video
  • 29 = ogg video
width Number Width of the asset, in pixels, if relevant.

EB.getAssetURL (localPath, ebAsset) {

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
GetAssetURL(asset:String):String
Parameters

(optional) additional asset numberIntegerThe number of the additional asset as it was defined in the Sizmek MDX platform e.g., "ebMovie1".

Name Type Description
asset String The ordinal number, file name, or URL of the asset to search for in urlParams.
(optional) additional asset Integer The number of the additional asset as it was defined in the Sizmek MDX platform e.g., "ebMovie1".
Example
EB.getAssetUrl('FolderName\\video.webm', 1)

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

function getDimensions()
Returns Response

Returns object with width and height properties.

Name Type Description
width Number Width dimension
height Number Height dimension

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.

Note: 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 the Sizmek MDX platform for the initial positioning of the ad.

Code Syntax
function initExpansionParams(x, y, width, height) 
Parameters
Name Type Description
x Number Defines the left offset (x-coordinate) of the collapsed-state rectangle relative to the expanded-state rectangle.
y Number Defines the top offset (y-coordinate) of the collapsed-state rectangle relative to the expanded-state rectangle.
width Number The width of the expanded-state rectangle.
height Number The 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 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); 

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

function getVisibilityData()
Returns Response

Returns an object with the following properties:

Name Type Description
available Boolean (Always present) Determines whether viewability data is being scanned or collected for this asset.
assetId String (Optional) a unique ID for the asset (banner or panel) on the page
customData Object (Optional) Miscellaneous data, ususally 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 properties top, left, bottom, right, width, and height.

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

function isAutoExpandEnabled()
Returns Response
Type Description
Boolean True/False

EB.isInitialized()

Description

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

Code Syntax

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

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.

Parameters
Name Type 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.

isMobileDevice

Description

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

Response Parameters

Returns true/false boolean value.

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
Name Type Description
path String Workspace asset path

removeEventListener

Description

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

Code Syntax

function removeEventListener (subscription)
Parameters
Name Type Description
subscription Object Subscription object returned from the event subscription from which to unsubscribe. 

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

function resetCollapseTimer (panelName, resetTo)
Parameters
Name Type 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 Number of milliseconds to reset the collapse timer.

EB.setExpansionParams()

Description

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

Code Syntax
function setExpansionParams(x, y, width, height)
Parameters
Name Type Description
x Number Defines the left offset (x-coordinate) of the collapsed-state rectangle relative to the expanded-state rectangle.
y Number Defines the top offset (y-coordinate) of the collapsed-state rectangle relative to the expanded-state rectangle.
width Number The width of the expanded-state rectangle.
height Number The height of the expanded-state rectangle.
Example
EB.setExpansionParams(0, 0, 700, 400); 

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

function (options) 
Parameters

 

Name Type Description
options Object (Optional) Object with properties adPart [EBG.adPart] and panelName.
??? String (Optional)
  • To specify banner: { adPart: EBG.adPart.BANNER }
  • To specify the default panel: { adPart: EBG.adPart.PANEL }
  • To specify a different panel: { adPart: EBG.adPart.PANEL, panelName: "panel1" }

EB.showDefaultImage()

Description

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

Code Syntax
function 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
function startTimer(intName)
Parameters
Name Type Description
intName String The name of the interaction timer.
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

function stopTimer(intName)

Parameters
Name Type Description
intName String The name of the interaction timer.
Example
EB.stopTimer("myCustomTimerInteraction");

EB.startVideoTimer()

Description

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

Code Syntax
function startVideoTimer(localPath)
Parameters
Name Type Description
localPath String The local path to the video asset that started playing.
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
function stopVideoTimer(localPath)
Parameters
Name Type Description
localPath String

The local path to the video asset that stopped playing.

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, like clicking on a button, playing with an ad part, etc. The method receives the name of the interaction to be tracked.

Code Syntax
function userActionCounter(intName, clickURL)
Parameters
Name Type Description
intName String The name of the interaction to be tracked.
clickURL (optional) String The clickthrough URL that opens. If no URL is specified, the URL that is defined in the Sizmek MDX platform for the specified interaction is used instead.
Example

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

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

userSwipe

Description

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

Code Syntax

function userSwipe()

EB.videoInteraction()

Description

Tracks a video interaction for a specified asset.

Code Syntax
function videoInteraction(intName, localPath)
Parameters
Name Type Description
intName   The name of the video interaction. This is typically one of the values in the EBG.VideoInteraction enum.
localPath String The local path to the specified asset.
Example
EB.videoInteraction(EBG.VideoInteraction.STARTED, "myVideos/trailer.mpg");
Was this article helpful?
4 out of 21 found this helpful
Have more questions? Submit a request

Comments