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: 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  
Multiple panel communications  
Multiple ad communications   Same Campaign Only.
Custom script to banner/panel communications Endpoints must be served from the same origin server, due to browsers ‘same origin’ policy.
Ad Server to Ad Server communications within same campaign   Endpoints must be served from the same origin server, due to browsers ‘same origin’ policy.
Communication between browser windows or tab   Within the same window tab only.

Configuring the Comm Module

The Comm module is an additional module that is part of your ads infrastructure. The initialization action automatically loads the Comm module in the index.html files when the ad is served.

The Comm module should be added to the index.html files of all the ad parts (banner and/or panels) that need to communicate.

Procedure
  1. Open the index.html file in a text editor.
  2. Add the Comm module code to the index.html file. This adds an additional notifier to the module array.
    EBModulesToLoad = ['Comm'];
    The EBModulesToLoad code should be added to thesection of your html before any reference to EBLoader or AdKit.
     
    If your
    index.html
    file already has an EBModulesToLoad declaration, add Comm to the existing line.
     
    EBModulesToLoad = ['EBV', 'Comm'];

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

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

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.

Public EB.Comm Methods 

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 The 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.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.isConnected(names)

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

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 Name(s) of the windows in which the function shouldbe 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.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");

 

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

Comments