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

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

Use this object to track a banner's in-screen parameters from the asset.

Methods:

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

  • 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 (Boolean) — is true when a banner is visible or false when it's not.

  • percent (Number) — 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 after the page loads. This helps to avoid blinking when expanding a double file expanding banner.

Restart animation is no longer supported in an HTML asset, so you should add, stop, or remove unwanted content depending on asset state by yourself. 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:

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.

  • 'show' — fires when an asset has been shown.

  • 'hide' — fires when an asset has been hidden.

An example of a polite banner:

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

Reserved Banner Events

Event Title

Event ID

Engaging

Auto Event

Banner Type

Comment

Custom Events

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 / Expand Events

First Expand

21

Yes

Expanding banner

First Expand of Expanding Banner.

Other Expands

22

Yes

Expanding banner

Second to Nth Expand of Expanding Banner.

Close Button Press

23

No

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

Close button press on expanding, floating, tear back, video cube banners.

Floating Banner Shown

24

Yes

Floating banner

Will improve floating banners statistic in synchronized banners.

Mouse Over on Banner

141

Yes

All banner types

The Mouse Over event is a user-initiated event which is only registered when the mouse stays on a banner for more than 1 sec.

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 page content is pushed down with the floating panel appearing on top. 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 as 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 is zoomed 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 with only the banner stage standing 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

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 it was set) was shown when a video finished playing.

Video Poster Press

177

Yes

Video banner

Video Poster Press is a user-initiated event which is only registered when a click is made on a Poster (image).

AVOC

185

No

Yes

VAST 4

Audible and Viewable on Complete

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

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

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

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 is fired for each item loaded on Product Banner. Event is fired while items are being scrolled too.

Other Events

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.

IAB Rising Stars

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, scrolling the webpage content to the left. See the preview of a banner here.

The Launch Slider Bar banner event is registered when a user clicks the action button and the Slider Content appears.

Close Slider Bar

163

No

Auto

IAB Slider

The Close Slider Bar banner event is registered when a user clicks the Close button placed on a slider bar or, alternatively, clicks the action button (for example, Slide back) placed under the Slider Content.

Cube Events

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!