Follow

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

Initializing the API 

The API requires performing the following procedure to make its functions available in the ad.

Procedure

  1. If you have video in your ad, and you want to track interactions, add the following code:
    Code
    <script type="text/javascript">
    EBModulesToLoad = ['Video'];
    </script>

    After EBLoader scans the creative and finds the EBModulesToLoad array with 'Video', it will then know to load the EBV script. Because of this, this code must be added before the code in the next step.
    For more information about declaring EBV script, see Declaring Usage of EBV Scripts.

  2. To use the API, include the following line early in the ad's HTML, such as in its head tag.
    Code
    <script type="text/javascript" src="http://ds.serving-sys.com/BurstingScript/EBLoader.js"></script>
  3. Use the following code when running ads on HTTPS servers.
    Code
    <script type="text/javascript" src="https://secure-ds.serving-sys.com/BurstingScript/EBLoader.js"></script>
  4. To initialize the API, add the following code as early as possible to the body element in the ad's HTML file.
    Code
    <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>

    Field Description
    • onInit is a custom function name and can be any name as long as it is also replaced in EB.addEventListener.
    • Inside onInit, it might be useful to call EB.addEventListener to listen to the ‘page load’ event if you want to load the ad politely.
    • For expandable ads, you must initialize the expansion parameters. For example:
      Code Sample
      EB.initExpansionParams(68, 171, 768, 614);

      (It is mandatory for this call to exist in the HTML file of a Single Expandable Banner ad).

Important: No EB function should be called before the EB object is initialized.

API Functions

The following API functions are available: 

addEventListener()

function addEventListener(eventName, callback, callbackBinding)

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

Parameters

Name

Type

Description

eventName

EBG.EventName

The name of the event that is being listened for. The following events are currently available:

  • EBG.EventName.EB_INITIALIZED: Dispatched when the API is initialized.
  • EBG.EventName.PAGE_LOAD: Dispatched when the page is fully loaded.
  • EBG.EventName.SDK_DATA_CHANGE: Dispatched each time data changes as a result of an event. Use when building ads that are compliant with MRAID (Mobile Rich Media Ad Interface Definitions).

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

MRAID is the Interactive Advertising Bureau's (IAB) project to define a common API for mobile rich media ads that run in mobile apps.

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

Example

EB.addEventListener(EBG.EventName.SDK_DATA_CHANGE,onDataChanged);

function onDataChanged(dataObj){

where:

  • onDataChanged is the callback handler
  • dataObj is the parameter received when onDataChanged is triggered. It includes:
    • 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.

getSDKData

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

Code

var SDKData = EB.getSDKData(); 

The properties of the object as listed above.

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.

automaticEventcounter()

function automaticEventCounter(intName, clickURL)

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.

Parameters

Name

Type

Description

intName

String

The name of the interaction to be tracked.

clickURL (optional)

String

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

browserSupports()

function browserSupports(featureName)

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

Parameters

Name

Type

Description

featureName

String

A string that is used to identify the feature that is being checked. For example, 'canvas', 'video', etc.

Returns

Type

Description

Boolean

BrowserSupports returns a true/false boolean value:-' 

 

// Shows the default image if the browser supports the <canvas> element

if (!EB.browserSupports('canvas'))

EB.showDefaultImage(); 

Clickthrough()

function clickthrough(intName, clickURL)

Tracks a clickthrough custom 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 default interaction (click) that is defined on the ad level.

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

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

collapse()

function collapse()

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

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

(mandatory)

String

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

 

expand()

function expand(expansionParams)

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.

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)

 

 

 

EB.expand();

var expansionParams = {

x: 0,

y: 0,

width: 300,

height: 350,

actionType: EBG.ActionType.AUTO

};

EB.expand(expansionParams); 

getAssetURL()

public static function GetAssetURL(asset:String):String

Returns the URL of a valid asset file.

Returns "" if the asset was not located.

Parameters

Name

Type

Description

 asset

 String

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

(optional) additional asset number

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) 

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

initExpansionParams()

function initExpansionParams(x, y, width, height)

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.

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 below:

For a 728x90banner expanding to a 728x200 panel:

Expansion downwards:

EB.initExpansionParams(0,0,728,200);

Expansion upwards:

EB.initExpansionParams(0,110,728,200); 

isInitialized()

function isInitialized()

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

Returns

Type

Description

Boolean

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

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

setExpansionParams()

function setExpansionParams(x, y, width, height)

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

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

 

showDefaultImage()

function showDefaultImage()

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

Example

if (!EB.browserSupports('canvas'))

EB.showDefaultImage(); 

 

startTimer() 

function startTimer(intName)

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

Parameters

Name

Type

Description

intName

String

The name of the interaction timer.

 

Example

EB.startTimer("myCustomTimerInteraction");

 

stopTimer()

function stopTimer(intName)

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

Parameters

Name

Type

Description

intName

String

The name of the interaction timer.

 
Example

EB.stopTimer("myCustomTimerInteraction");

 

startVideoTimer()

function startVideoTimer(localPath)

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

Parameters

Name

Type

Description

localPath

String

The local path to the video asset that started playing.

 
Example

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

 

stopVideoTimer()

function stopVideoTimer(localPath)

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

Parameters

Name

Type

Description

localPath

String

The local path to the video asset that stopped playing.

 

Example

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

 

Smart Versioning

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

userActionCounter()

function userActionCounter(intName, clickURL)

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.

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 platform

EB.userActionCounter("myUserActionInteraction");

// Tracks custom interaction specifying the redirect URL

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

 

videoInteraction()

function videoInteraction(intName, localPath)

Tracks a video interaction for a specified asset.

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

  • Avatar
    Sushil Kokate

    Somebody please review and correct the portion below the section

    collapse()

    The example of EB.collapse() not proper. And below there is description of EB.getAssetURL() instead of EB.collapse()