Use Public Methods for HTML5 Banners

Vaida
Vaida
  • Updated

Public methods are publicly available functions that are defined in the Adform DHTML library. When building HTML5 banners, use public methods to make banners clickable, to track events, and to implement other banner functions. To use public methods, first add Adform DHTML library to your HTML5 banner.

List of Public Methods for Banners in Adform

Public method

Description

dhtml.getVar(name, undefined_fallback)

Returns a string value of the name banner variable or a provided default value if the variable doesn't exist.

To get values of clickTAG or landingPageTarget variables from the system if these variables aren't present, use the default expression:

clickTAGvalue = dhtml.getVar('clickTAG', 'http://test.page.com/');
landingPageTarget = dhtml.getVar('landingPageTarget', '_blank');

dhtml.sendEvent(id, name, vars)

Registers an event in Adform. When sending an event, the custom event ID (var id) must be from 1 to 19, the name object is required, and the vars object is optional. In the following example, vars objects are { bv1: "John", bv2: "Colin", bv3: "24" }:

button.onclick = function() {
                var id = 1,
                name = 'banner click',
                eventVars = {
                    bv1: "John",
                    bv2: "Colin",
                    bv3: "24"
                };

            dhtml.sendEvent(id, name, eventVars);
            return false;
        };

dhtml.getAsset(id)

Returns URL of the asset with the given ID or returns "undefined" if that asset doesn't exist.

var url = dhtml.getAsset(1); //A call to the function with the asset id.

dhtml.inscreen

Tracks a banner's in-screen parameters from the asset. You can use this method to track the following:

Methods:

  • on(type, callback) — adds an event listener.

    An event listener is a way to wait for user interaction (such as a click) and fire a specific code once that interaction happens.

  • once(type, callback) — adds an event listener and removes it after the event fires.

  • off(type, callback) — removes the event listener.

Events:

  • 'visible' — fires when the banner's visible parameter changes.

  • 'percent' — fires when the banner's percent parameter changes.

  • 'change' — fires when any of the banner's parameters change.

Note

Every event (except 'change') passes the value argument to its callback. This argument holds the latest value of the banner's in-screen parameter.

Properties:

  • visible — A boolean variable . This property is true when a banner is visible or false when it's not.

  • percent — A number variable. This property holds the banner's visibility percent value (from 0 to 100).

Example inscreen code:

  dhtml.inscreen
    .on('visible', function (value) { console.log('visible change', value); })
    .on('percent', function (value) { console.log('percent change', value); })
    .on('change', function () {
      console.log('some change', {
        visible: this.visible,
        percent: this.percent
      });
    });

dhtml.external

  • expand() — expands the banner from the asset (used in expandable banner types).

  • close() — collapses or closes a floating banner.

  • superClose() — closes and destroys the entire banner.

  • initPoliteMode() — announces that the asset is ready to load heavy content (used with dhtml.sharedEvents.on('pageLoadComplete', listener)).

  • updateBox(x, y, width, height) — is used by Adform.SingleExpanding.

  • expandComplete() — is used by Adform.SingleExpanding.

  • collapseComplete() — is used by Adform.SingleExpanding.

  • initScroll() — is used by Adform.FilmStrip.

  • initSingleExpanding(x, y) — is used by Adform.SingleExpanding.

  • toggleFullScreen(status) — is used by Adform.VideoPlayer.

An Interactive Banner Method

includeAPI() — a method that loads the Adform.DHTML.js file from the appropriate Adform servers. It adds a document writing script, such as:

doc.write('<script src="'+fv.staticDomain + 'scripts/rmb/Adform.DHTML.js?bv='+ fv.bv+'"><\/script>');

Preload and States

Even if an HTML asset isn't visible, it is preloaded in the background and ready for display. This helps to avoid blinking when expanding a double file expanding banner.

HTML assets no longer support restart animation. Therefore, you must define when to add, stop, or remove content depending on asset state. An HTML asset has three states: initial, visible, and hidden. You can get the current state of the asset using dhtml.getState() or listen for state change events through dhtml.sharedEvents.

Example code to return the current state of the asset:

var state = dhtml.getState();

console.log('The current state is: ' + state);

dhtml.sharedEvents.on('changed:state', function (s) {
    console.log('Last state was: ' + state);
    console.log('State has changed to: ' + s);
    state = s;
});

Shared Events

To listen to banner-specific events, you can use a dhtml.sharedEvents object to add or remove event listeners.

  • on(type, callback) — adds an event listener.

  • once(type, callback) — adds an event listener and removes him after the event fires.

  • off(type, callback) — removes an event listener.

Currently, Adform supports the following public events:

  • 'pageLoadComplete' — fires when a page is loaded. This event is commonly used to set up polite banners.

    Polite banners show an image while the page is loading and loads heavy content (such as video) only after the page has fully loaded. An example of a polite banner:

    dhtml.sharedEvents.once('pageLoadComplete', function() {
    // traffic-heavy code here
});
dhtml.external.initPoliteMode();

  • show — fires when an asset has been shown.

  • hide — fires when an asset has been hidden.

Reserved Banner Events

Custom Events

Event Title

Event ID

Engaging

Auto Event

Banner Type

Custom Engaging Event 1 ... Custom Engaging Event 20

From 1 to 20

Yes

All banner types

Custom Event 200 ... Custom Event 250

From 200 to 250

No

All banner types

Rich Media and Expand Events

Event Title

Event ID

Engaging

Auto Event

Banner Type

Comment

First Expand

21

Yes

Expanding banner

The first expansion of the expanding banner

Other Expands

22

Yes

Expanding banner

Second to nth expansion of the expanding banner

Close Button Press

23

No

Expanding, Floating, Tear Back, Video Cube, In-Stream banner

The press of close button on expanding, floating, tear back, video cube banners

Floating Banner Shown

24

Yes

Floating banner

Improves floating banners statistic in synchronized banners

Mouse Over on Banner

141

Yes

All banner types

A user initiates the mouse over event when they stay on a banner for more than 1 second

Banner Collapse

143

No

Expanding, Tear Back banner

Hide Expanding Banner Button Press

161

No

Super Close banner

Home Panel Shown

164

Yes

Glider banner

A user opens the webpage and sees a banner in the placement. On a click, the floating panel appears on top and pushes the page content down. The user can select among three panels by clicking on Left, Home (Center), Right buttons, each of them moving the page content accordingly. See the preview of a banner here.

The Home Panel Shown banner event indicates that a user has clicked on the Home button and a page content has been moved to the center

Left Panel Shown

165

Yes

Glider banner

The Left Panel Shown banner event indicates that a user has clicked on the Left button and a page content has been moved to the left

Right Panel Shown

166

Yes

Glider banner

The Right Panel Shown banner event indicates that a user has clicked on the Right button and a page content has been moved to the right

Auto Expands

168

No

Auto

Expanding banner

The Auto Expands banner event indicates that a banner expanded automatically, for example, without a user interaction

Zoom In

170

Yes

Polite Zoom banner

A user opens the webpage and sees the banner in the placement. On mouse over or click on the Zoom In button, the banner zooms in while the content of the webpage zooms out. The ad maintains this position until the user leaves the button area or clicks Zoom Out. See the preview of a banner here.

The Zoom In banner event is registered when a user mouses over or clicks the Zoom In button

Zoom Out

171

No

Polite Zoom banner

The Zoom Out banner event is registered when a user leaves the zoomed in banner area or clicks the Zoom out button of the banner

Dim In

172

Yes

Background Dimmer banner

A user opens a webpage and sees the banner in the placement. Once the user rolls over the banner, the whole webpage becomes darker and only the banner stage stands out in its initial state. See the preview of a banner here.

The Dim In event is registered on the roll over

Dim Out

173

No

Background Dimmer banner

The Dim Out banner event is registered when a user leaves the banner area and the webpage comes back to its initial experience

Video Events

Event Title

Event ID

Engaging

Auto Event

Banner Type

Comment

Video Play Start

25

No

Auto

In-Stream and video banner

25% of Video Play

26

No

Auto

In-Stream and video banner

50% of Video Play

27

No

Auto

In-Stream and video banner

75% of Video Play

28

No

Auto

In-Stream and video banner

Video Complete

29

No

Auto

In-Stream and video banner

Play Button Press

30

Yes

Video banner

Pause Button Press

31

Yes

In-Stream and video banner

Stop Button Press

32

Yes

Video banner

Sound On Button Press

33

Yes

In-Stream and video banner

Sound Off Button Press

34

Yes

In-Stream and video banner

Full Screen On Button Press

35

Yes

In-Stream and video banner

Full Screen Off Button Press

36

Yes

Video banner

Resume Button Press

37

Yes

In-Stream and video banner

Rewind Button Press

38

Yes

In-Stream and video banner

Replay Button Press

39

Yes

Video banner

Video Poster Shown

176

No

Auto

Video Banner

Video Poster Shown event indicates that a poster (image), if one was set, was shown when a video finished playing

Video Poster Press

177

Yes

Video banner

A user initiates Video Poster Press event when they click on a poster (image)

AVOC

185

No

Yes

VAST 4

AVOC (Audible and Viewable on Complete) event indicates that a video banner was audible and viewable on completion

Viewable at 0%

180

No

Yes

VAST 4

Video playback has reached 0% and was in-screen (at least 50% of the video was on the screen)

Viewable at 25%

181

No

Yes

VAST 4

Video playback has reached 25% and was in-screen (at least 50% of the video was on the screen)

Viewable at 50%

182

No

Yes

VAST 4

Video playback has reached 50% and was in-screen (at least 50% of the video was on the screen)

Viewable at 75%

183

No

Yes

VAST 4

Video playback has reached 75% and was in-screen (at least 50% of the video was on the screen)

Viewable at 100%

184

No

Yes

VAST 4

Video playback has reached 100% and was in-screen (at least 50% of the video was on the screen)

In-Stream Events

Event Title

Event ID

Engaging

Auto Event

Banner Type

Comment

Linear Creative View

40

No

Auto

In-Stream banner

Linear Creatives involve a time-limited video advertisement that can be shown before, in the middle of, or after a user sees content in a video player

Non Linear Creative View

41

No

Auto

In-Stream banner

The Non-Linear Creatives run concurrently with video content, therefore, users can see in-stream ads while viewing the content

Companion Creative View

42

No

Auto

In-Stream banner

Companion Creatives run adjacent to the player content window and can involve image or Flash files

Skip Video

169

No

In-Stream banner

Viewable Impression

110

No

Auto

In-stream banner ( VAST 4.0 )

Fires automatically when the ad meets criteria for a viewable video ad impression

Not Viewable Impression

111

No

Auto

In-stream banner ( VAST 4.0 )

Fires automatically if the ad is executed but never meets criteria for a viewable video ad impression

Undetermined Impression

112

No

Auto

In-stream banner ( VAST 4.0 )

Fires automatically if it's impossible to determine whether the ad has met criteria for a viewable video ad impression

Social Events

Event Title

Event ID

Engaging

Banner Type

Share to Facebook

50

Yes

All banner types

Share to Instagram

51

Yes

All banner types

Share to Twitter

52

Yes

All banner types

Share to Linkedin

53

Yes

All banner types

Share to Pinterest

54

Yes

All banner types

Share to Google Plus+

55

Yes

All banner types

Share to Tumblr

56

Yes

All banner types

Share to Flickr

57

Yes

All banner types

Facebook Like Button Press

140

Yes

All banner types

Product Banners

Event Title

Event ID

Engaging

Auto Event

Banner Type

Comment

Show Next Product(s)

150

Yes

Product Ads

Show Previous Product(s)

151

Yes

Product Ads

Dynamic Product View

152

Yes

Auto

Product Ads

Product View event fires for each item loaded on product banner. Event fires while the user scrolls the items too.

Other Events

Event Title

Event ID

Engaging

Auto Event

Banner Type

Comment

Impression Served

174

No

Auto

Mobile banner

Impression Served event indicates server-side impressions for mobile devices. (In Adform, impressions by mobile devices are calculated on the client side).

This is a technical event used for checking discrepancies (not IAB)

Impression Fully Loaded

175

No

Auto

Mobile banner

Impression Fully Loaded event indicates that an ad was fully rendered (but not necessarily seen) in a mobile app, which uses Adform Advertising SDK

Viewable Impressions

178

No

Yes

All banner types

Viewable Impression event shows when a banner was seen in user screen based on IAB defined standard viewability parameter thresholds. This event works only with programmatic line items.

IAB Rising Stars

Event Title

Event ID

Engaging

Auto Event

Banner Type

Comment

Show Next Filmstrip Panel

153

Yes

IAB Filmstrip

IAB Filmstrip banner consists of several interactive panels

The Show Next Filmstrip is a user-initiated banner event which, on a click, mouse or browser scroll, or on a repeated visit, shows the next panel

Show Previous Filmstrip Panel

154

Yes

IAB Filmstrip

The Show Previous Filmstrip is a user-initiated banner event which, on a click, mouse or browser scroll, or on a repeated visit, shows the previous panel

First Filmstrip Panel Shown

155

No

Auto

IAB Filmstrip

Second Filmstrip Panel Shown

156

No

Auto

IAB Filmstrip

Third Filmstrip Panel Shown

157

No

Auto

IAB Filmstrip

Fourth Filmstrip Panel Shown

158

No

Auto

IAB Filmstrip

Fifth Filmstrip Panel Shown

159

No

Auto

IAB Filmstrip

Launch Slider Bar

162

Yes

IAB Slider

A user opens the webpage and sees the floating browser-width Slider Bar anchored at the bottom of the browser window and, optionally, a banner in the placement. The Slider Bar and the banner accommodate a call to action button. On a click, the Slider Content appears on the right side of the page and scrolls the webpage content to the left. See the preview of a banner here.

A user initiates the Launch Slider Bar banner event when they click the action button and the slider content appears

Close Slider Bar

163

No

Auto

IAB Slider

A user initiates the Close Slider Bar banner event when they click the close button placed on a slider bar or, alternatively, click the action button (for example, Slide back) placed under the slider content

Cube Events

Event Title

Event ID

Engaging

Auto Events

Banner Type

Rotate Cube Forward

120

Yes

Cube banner

Rotate Cube Backward

121

Yes

Cube banner

First Side Shown

122

No

Auto

Cube banner

Second Side Shown

123

No

Auto

Cube banner

Third Side Shown

124

No

Auto

Cube banner

Fourth Side Shown

125

No

Auto

Cube banner

Fifth Side Shown

126

No

Auto

Cube banner

Sixth Side Shown

127

No

Auto

Cube banner

Was this article helpful?

/
How we can make it better?

Thank you for your feedback!