PRODUCT
Follow

Overview

The HTML5 Comm module enables communication between elements in the ad and between different ads. For example, an HTML5 Expandable ad's banner and panel elements can communicate with an HTML5 Rich Media banner on the same page, as long as they are all in the same campaign. You can trigger simultaneous animations and functions across all your advertisements, which provides a dynamic and seamless experience and overall control.

The HTML5 Comm module resolves iFrame limitations and provides direct script communication between all your ad elements (banners, panels, and iFrames) on the same page, within the same campaign. HTML5 ads are served into iFrames. The iFrame acts as a sandbox, preventing JavaScript inside from accessing other content on the page, including other ads. In HTML5 Expandable ads, the banner and panel are separate iFrames, and therefore are unable to communicate with each other. The Comm module overcomes this restriction, allowing easy access between ads on the same page, as well as between the banner and panel iFrames of the same ad.

Typical use cases include triggering an In-Banner animation when the panel collapses, or starting a video or animation simultaneously in multiple ads.

Note

Note: The Comm module file adds 1 kb to the size to your ad, and is typically hidden within the ad loading files during serving.

The following table describes the functionality supported by the Comm module.

Functionality

Supported

Scope

Banner and panel communications

DOC_tick.gif

Multiple panel communications

DOC_tick.gif

Multiple ad communications

DOC_tick.gif

Same Campaign Only.

Custom script to banner/panel communications

DOC_cross_blue.jpg

Endpoints must be served from the same origin server, due to browsers ‘same origin’ policy.

Ad Server to Ad Server communications within same campaign

DOC_cross_blue.jpg

Endpoints must be served from the same origin server, due to browsers ‘same origin’ policy.

Communication between browser windows or tab

DOC_cross_blue.jpg

Within the same window tab only.

Initializing the Comm Module

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

            EBModulesToLoad = ['Comm'];
          

The EBModulesToLoad code should be added to the section of your html before any reference to AdKit (or EBLoader).

If your index.html file already has an EBModulesToLoad declaration, add Comm to the existing line.

            EBModulesToLoad = ['Video', 'Comm'];
          

For more information, see HOW TO: Load and Initialize the API.

Testing the Comm Module on Your Local PC

You can test the Comm Module on your local PC. The Comm module only supports communication within a single browser window. If you want to test your ad locally before uploading, you need to load all of your ad-parts into iFrames in a single html file.

Use Case Examples

Calling a Function in Another Ad or Ad Part

Procedure
  1. Call a function in a source window.

  2. Create a reference to the destination window. To get that reference,you must call EB.Comm.setName(...). After .setName() has been called, all the ad windows, (belonging to the same campaign), on the page will have a reference to it inside their EB.Comm object, as EB.Comm.<name>.

  3. Proceed to call functions directly using syntax like EB.Comm.<name>.myFunc();.

    Banner iFrame Code

                  
    function onInit() {
        if (!EB.isInitialized()) EB.addEventListener(EBG.EventName.EB_INITIALIZED, start);
        else start();
    }
    
    function start() {
        EB.Comm.setName("banner300x250");
    }
    
    function showCloseAnimation() {
        //do stuff
    }
    
                

    Panel iFrame Code

                  
    function onInit() {
        if (!EB.isInitialized()) EB.addEventListener(EBG.EventName.EB_INITIALIZED, start);
        else start();
    }
    
    function start() {
        //do stuff, such as adding click event listener
    }
    
    function onCloseButtonClick() {
        EB.Comm.banner300x250.showCloseAnimation();
        EB.collapse();
    }
    
                

Starting an Animation Simultaneously in Two or More Ad IFrames

Use the callWhenConnected() method to call the same named function in two or more Worksapces (Creative Elements, IFrames, or Windows).

In the following example, the function startAnimation exists in both windows, and will be called in both places at the same time, when both elements have made their call to .setName(...).

Banner iFrame Code

               
function onInit() {
    if (!EB.isInitialized()) EB.addEventListener(EBG.EventName.EB_INITIALIZED, start);
    else start();
}

function start() {
    EB.Comm.callWhenConnected(["banner300x250", "panel1500x300"] "startAnimation");
    EB.Comm.setName("banner300x250");
}

function startAnimation() {
    //do stuff
}

            

Panel iFrame Code

              
function onInit() {
    if (!EB.isInitialized()) EB.addEventListener(EBG.EventName.EB_INITIALIZED, start);
    else start();
}

function start() {
    EB.Comm.setName("panel1500x300");
}

function startAnimation() {
    //do stuff
}

            

Showing Content on Interaction/ State in the Banner

The panel should request information from the banner every time it expands. Setting a callWhenConnected in the banner is not enough because the banner cannot detect when the panel is collapsing, so it cannot add a new call to callWhenConnected, to be ready for the next expansion.

Banner iFrame Code

              
var state = 0;

function onInit() {
    if (!EB.isInitialized()) EB.addEventListener(EBG.EventName.EB_INITIALIZED, start);
    else start();
}

function start() {
    //some kind of logic to determine the value of "state"
    state = 1;
    //set a name so that the "requestState" function can be called from the panel
    EB.Comm.setName("banner300x250");
}

//This function will be called directly by the panel.
function requestState(who) {
    //Check that the window and function to be called both exist already.
    if (EB.Comm.isConnected(who) && EB.Comm[who].setState) {
        //Call the function in the panel window.
        EB.Comm[who].setState(state);
    }
}

            

Panel iFrame Code

              
var state = 0;
var syncTimeout;

function onInit() {
    if (!EB.isInitialized()) EB.addEventListener(EBG.EventName.EB_INITIALIZED, start);
    else start();
}

function start() {
    //Set a name so that the "setState" function can be called from the banner.
    EB.Comm.setName("panel300x300");
    //Call "requestState in the banner as soon as we have a connection, which should be immediately.
    EB.Comm.callWhenConnected("banner300x250", "requestState", "panel300x300");
    //Use a timeout as a "Plan B", just in case something goes wrong.
    syncTimeout - setTimeout(startWithoutSync, 5000);
}

//This function will be called directly by the banner.
function setState(value) {
    clearTimeout(syncTimeout);
    state - Value;
    startAnimation();
}

function startWithoutSync(value) {
    clearTimetout(syncTimeout);
    startAnimation();
}

function startAnimation() {
    //do something with the state value, like show a different video or whatever
}

            

Public EB.Comm Methods

EB.Comm.broadcast

Description

Calls a named function in the Comm objects in all available iFrames. The function is called, if it exists, in all of the creative iFrame elements from the same campaign on the page, whether they have provided a name for themselves yet or not. There is no return value.

Parameters

NAME

TYPE

DESCRIPTION

funcName

String

Name of the function to call, including the path from the window namespace.

args

Array

Arguments to apply to the function.

Return Value

None/ Undefined.

Example

Collapses all panels named exp that belong to all ads on the page.

              EB.Comm.broadcast("EB.collapse", "exp");
            

EB.Comm.callWhenConnected

Description

Sets up a function call to be made in each of a list of windows when all of those windows become available for calling. The named function must already exist in all the specified windows. If the named function does not exist in any of the windows, the call will fail silently, and proceeds to the next window in the list, if any.

Parameters

NAME

TYPE

DESCRIPTION

windowNames

String/Array

Names of the windows in which the function should be called.

funcName

String

Name of the function to be called in each of the windows.

args

Array

Arguments to pass to the function.

Return Value

None/ Undefined.

Example

              EB.Comm.callWhenConnected("banner300x250", "doStuff", 1); // returns undefined
            

EB.Comm.getName

Description

Retrieves the name of the Comm object.

Parameters

NAME

TYPE

DESCRIPTION

name

String

Name of the Comm object.

Return Value

TYPE

DESCRIPTION

String

Name that has been set.

Example

              EB.Comm.getName(); // returns "banner" or whatever you previously set using "setName()"
            

EB.Comm.setName

Description

Sets a public name for the Comm object in the creative element (iFrame window) so that it can be discovered.

Example

              EB.Comm.setName(name)
            

Parameters

NAME

TYPE

DESCRIPTION

name

String

Name of the Comm object.

Return Value

TYPE

DESCRIPTION

String

Name that has been set.

Console Example

              EB.Comm;
           //returns EBG.Comm {}
EB.Comm.setName("banner");     
          //"banner"
EB.Comm;  // returns EBG.Comm {banner: Window} - now it has a property called "banner", of type "Window"
          // You now have a reference to the window inside your Comm object. 
          // Any other Comm objects on the page will now also have this same reference.
            

This name appears in the Comm objects of all the connected windows as a reference to the current window.

EB.Comm.isConnected()

Description

Checks if an element, specifically the Comm object inside an ad iFrame window or list of elements have been loaded and made themselves available for Comm.

Parameters

NAME

TYPE

DESCRIPTION

name

String

Name or array of names to check.

Return Value

TYPE

DESCRIPTION

Boolean

The options are:

  • True if all the names are found.

  • False if any of the names are missing or not yet discovered.

Example

              
EB.Comm.isConnected("banner300x250"); //returns true (or false if you passed anything other than "banner300x250" to the "setName method)
EB.Comm.isConnected(["banner300x250", "panel500x300"]); // returns true or false

            
Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments