Code HTML5 Banners

Vaida
Vaida
  • Updated

HTML5 banner ads are a collection of multiple files, including various image and video components, as well as a .html source file.

Click the banner to preview some examples of rich media and standard ads in Adform Creative Showroom:

Loreal

20th Century Fox

Lyric
Loreal.png
Lyric.png
Sprite.png

An HTML5 banner must have at least two files, which are compressed into a single .zip file:

banner.zip
├── manifest.json
└── banner.html

The manifest.json file defines banner parameters (such as name, description, dimensions). The banner.html file is the one that links all the different sources and components (images, videos, and others) and includes the necessary code for animations, interactions, and other HTML5 banner functions to work.

Adform has specifications that must be met for HTML5 ads to be uploaded to the Adform system and work as intended. Before you work on HTML5 ads, make sure to get familiar with the required banner file structure in Requirements for HTML5 Banner Files.

Add Adform DHTML Library to HTML

Every HTML5 banner uploaded to Adform must have Adform DHTML library inserted within the <head> tags of the HTML file:

<script>
    document.write('<script src="' + (window.API_URL || 'https://s1.adform.net/banners/scripts/rmb/Adform.DHTML.js?bv=' + Math.random()) + '"><\/script>');
</script>

Work with DHTML Library: dhtml.getVar

DHTML library provides various functions for the banner in dhtml and Adform methods. The most important one is receiving a clickTAG value inside of a banner:

const clickTAGvalue = dhtml.getVar('clickTAG', 'https://example.com');

This allows the banner to click through — to send the user to a desired landing page while also tracking a click in Adform.

Note

clickTAG variables make the banner clickable. For an HTML5 ad to work properly, make sure the variables are set up correctly. You can learn how to add a clickTAG variable in the Add Click Tag Variables article.

How Does dhtml.getVar Work?

dhtml.getVar takes two arguments:

dhtml.getVar('variableInAdform', 'local fallback value');

variableInAdform is any variable (a banner property) defined in the Adform system (such as predefined ones: clickTAG and landingPageTarget) or your own (for example, textColor).

The local fallback value is a default value used when you test the banner locally or when you test the banner in Adform but a variable (such as textColor) hasn't been defined in the Adform system.

Example of using dhtml.getVar to define text color

textfield.style.color = dhtml.getVar('textColor', '#FFFFFF');
// textfield text color can be changed by providing 'textColor' to Rich Media banner, if not provided color will be white.

How Does clickTAG Work?

clickTAG variables make the banner clickable and send the user to the desired landing page:

  1. You can receive a clickTAG value in a banner using this code:

    const clickTAGvalue = dhtml.getVar('clickTAG', 'https://example.com');

  2. After a user clicks, land them with this code:

    element.addEventListener('click', function(){
    window.open(clickTAGvalue, '_blank');
});

Locally (when the banner isn't in Adform), the banner lands directly to https://example.com.

However, when you upload the banner in Adform, Adform reads the clickTAG value and adds click tracking:

  1. First, Adform parses the manifest.json file and sees which and how many different clickthroughs the banner needs to support.

    • For Adform to see the banner clickthroughs, you need to assign landing pages (clickTAG values) in the manifest.json file, such as:

      clickTAG:   https://site.adform.com/
clickTAG2:  https://site.adform.com/company/about-adform/

  2. To track a particular click, Adform creates redirect links (clicktrackers) for the assigned landing pages (clickTAG values). This only works when the banner is live or in Adform.

    Assigned landing pages

    Landing pages with clicktrackers

    		 
    clickTAG:   https://site.adform.com/
clickTAG2:  https://site.adform.com/company/about-adform/
    		 
    clickTAG:   https://track.adform.net/C/?bn=1234567;C=1;more;various;params // which redirects to https://site.adform.com/
clickTAG2:  https://track.adform.net/C/?bn=1234567;C=2;more;various;params // which redirects to https://site.adform.com/company/about-adform/

Run this code to test how clickTAG works both on your local machine and when a banner is in Adform:

const clickTAGvalue = dhtml.getVar('clickTAG', 'https://example.com');
console.log('clickTAG:', clickTAGvalue);

Register Custom Engagements and Track Events in Banners: dhtml.sendEvent

Not all clicks in a banner need to click through and send a visitor to a website. Sometimes a custom action must be registered (for example, game started or game finished).

You can define events in the manifest.json file for Adform to know about any custom events in the banner:

{
    "events": {
        "enabled": 1,
        "list": {
            "1": "Some interaction in Banner"
        }
    }
}

To launch a custom event:

  1. In the banner's code, use the dhtml.sendEvent method:

    dhtml.sendEvent(1, 'Some interaction in Banner');

    Note

    The second argument ('Some interaction in Banner') won't appear in reports. For an event name to appear in reports, define it in the manifest.json file.

    If an event name isn't defined, a report shows an event such as CUSTOM_ENGAGING_EVENT_1. You can only rename an undefined event name in an exported report (for example, in a .xlsx file) if needed.

    Example of an undefined action:

    element.addEventListener('click', function(){
    dhtml.sendEvent(1, 'Some interaction in Banner');
});

    Example of defined actions:

    ...
dhtml.sendEvent(1, 'Game Started');
...
dhtml.sendEvent(2, 'Game Finished');
...

  2. If you want the custom event to track dynamic values, such as scores in a game, pass a "banner variable" (bv) object to the event:

    scores = {
    bv1: '100', // level 1 score
    bv2: '250', // level 2 score
    bv3: '150', // level 3 score
};

dhtml.sendEvent(2, 'Game Finished', scores);

    You can export a report that shows banner variables and their values in Banner Variables Data Export.

Other custom engagements can include clicks on specific banner areas and similar interactions. You can track events with static as well as dynamic values.

Note

You can test your HTML event tracking tags here and see a sample of HTML banner file with event tracking setup.

Add Dynamic Landing Pages

You may need to create a banner where a landing page must be formed dynamically. The banner can be set up to add URL parameters to a defined landing page, or to replace the landing page entirely.

In case the banner needs to pass parameters to the landing page's query string:

  1. Use ;urlappend= to define URL parameters:

    const clickTAGvalue = dhtml.getVar('clickTAG', 'https://example.com');
const custom = ';urlappend='+'?street=' + street + '&country=' + country + '&city=' + city + '&zip=' + zip;
// where street, city, country, zip comes from form in the banner or similar
window.open(clickTAGvalue + custom, '_blank');

  2. Test the landing page in Adform.

    When testing locally, the banner goes to an incorrect landing page because ;urlappend= is inserted in the middle of the landing page URL:

    https://example.com;urlappend=?street=streetname&country=countryname&city=cityname&zip=1234

    When testing the banner in Adform, however, a clicktracker is used:

    https://track.adform.net/C/?bn=1234567;C=1;more;various;params;urlappend=?street=streetname&country=countryname&city=cityname&zip=1234

    Then, the banner landing page redirects to:

    https://landingpagesetinadform.com/?street=streetname&country=countryname&city=cityname&zip=1234

In case the full landing page must be defined in the banner to override the landing page set in the system:

  1. Use ;cpdir= to define a new landing page:

    const clickTAGvalue = dhtml.getVar('clickTAG', 'https://example.com');
const custom = ';cpdir='+'https://landingpageformedinbanner.com';
// where street, city, country, zip comes from form in the banner or similar
window.open(clickTAGvalue + custom, '_blank');

  2. Test the landing page in Adform.

    When testing locally, the banner goes to an incorrect page because of how dhtml.getVar works:

    https://example.com;cpdir=https://landingpageformedinbanner.com

    When testing the banner in Adform, however, a clicktracker is used:

    https://track.adform.net/C/?bn=1234567;C=1;more;various;params;cpdir=https://landingpageformedinbanner.com

    Then, the banner landing page redirects to:

    https://landingpageformedinbanner.com

Continue Building Your HTML5 Banners

Once you have the basics, you can add public methods, reserved banner events, and more. Read about different banner formats supported in Adform and how to code them:

Was this article helpful?

/
How we can make it better?

Thank you for your feedback!