Follow

Overview

The Sizmek HTML5 API lets creative developers add Sizmek MDX platform tracking to their ads.

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: Before you can use the API, you must first load the EB object and wait for it to initialize. 

Initializing the API

Add an EBLoader.js reference in the head section of your document.

<script src="https://secure-ds.serving-sys.com/BurstingScript/EBLoader.js"></script>

To initialize the API, add the following code as early as possible to the body element in the ad's HTML file. isInitialized checks whether the EB object is fully initialized and available for API calls.

<script type="text/javascript">
        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 "EB_INITIALIZED" event. 
                }
                else {
                       onInit();
                }   
                function onInit() {
                      // Place your code to start the ad flow here
               }
      }
      window.addEventListener('load', checkInit);
</script>

API Functions

The following API functions are available: 

EB.addEventListener()

Description

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

Code Syntax 
function addEventListener(eventName, callback, callbackBinding)
Parameters

Name

Type

Description

eventName

EBG.EventName

The name of the event that is being listened for. To view a list of events, see REFERENCE: HTML5 API Events.

 

callback

function

The callback that is called when the event is dispatched.

callbackBinding (optional)

object

The 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); 

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

Name

Type

Description

onDataChanged

 

callback handler

dataObj

 

Received when onDataChanged is triggered:

  • eventName: The name of the SDK event that was triggered. sizeChange is currently the only supported SDK event.
  • 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.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

Name

Type

Description

onDataChanged

 

callback handler

dataObj  

Received when onDataChanged is triggered:

  • eventName: The name of the SDK event that was triggered. sizeChange is currently the only supported SDK event.
  • 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'.

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

Code Syntax
function clickthrough(intName, clickURL) 
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.collapse()

Description

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

Code Syntax
function collapse()
Example
EB.collapse();
var collapseParams = {
actionType: EBG.ActionType.AUTO
};
EB.collapse(collapseParams);

EB.collapse({panelName:"user-defined panel name"})

Parameters

Name

Type

Description

user-defined panel name String The name of the panel to be collapsed. If not mentioned, all panels will be collapsed.

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
function expand(expansionParams)
Parameters

Name

Type Description
expansionParams (optional) Object A JSON object 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. OrEBG.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.

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)

 

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

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)

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

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

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

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");

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 19 found this helpful
Have more questions? Submit a request

Comments