Code Creative Shells (Advanced DCO Ads)

Greta
  • Updated

To get front-end application functionality from dynamic ads, coding skills are required in order to get the data from Adform, manipulate data, and use creative animation.

Receive Information From Adform

To receive information from Adform:

  1. Include Adform's DHTML library into the <head> of the HTML file for the creative shell:

    <script>
        document.write('<script src="' + (window.API_URL || 'https://s1.adform.net/banners/scripts/rmb/Adform.DHTML.js?bv=' + Math.random()) + '"><\/script>');
    </script>
  2. To receive actual data from Adform include an AdMessage' call and then get a page, product, or item from it:

    Adform.AdMessage.build({        
        cid: dhtml.getVar('cid'),        
        tid: dhtml.getVar('tid'),        
        domain: dhtml.getVar('domain', 'https://track.adform.net/banners/'),        
        rotseqno: dhtml.getVar('rotseqno', 0),        
        clickTAG: dhtml.getVar('clickTAG', 'https://www.adform.com/'),        
        pageSize: 1,
    }).getItems([dhtml.getVar('gid', 0)], function (error, items) {        
        if (!error && items && items[0]) {            
            console.log(items[0]);        
        } else {            
            // something went wrong, default banner to some backup animation or similar        
        };    
    });

    Note

    With dhtml.getVar(argument1, argument2), argument1 is a variable to be received (a variable assigned to banner through the UI) from the ad server and argument2 is a fallback value. For example, dhtml.getVar('clickTAG', 'https://www.adform.com/') would receive a clickTAG data from Adform. If you test the banner locally or outside of Adform, the clickTAG's value would be https://www.adform.com/.

Build a Version Spreadsheet for Dynamic Ads

You can create a dynamic ads spreadsheet and assign it to the banner. You can then edit banner elements by editing that spreadsheet. The spreadsheet could look like this:

reportingLabel

Text:travelDestination

Image:image

Audience

Austria

Travel to Austria!

Photo-Austria

People interested in Europe

India

Travel to India!

Photo-India

People interested in Asia

Thailand

Travel to Thailand!

Photo-Thailand

People interested in Asia

For more information, see Build Version Spreadsheets for Dynamic Ads.

Code Dynamic Ads

To build dynamic ad, form AdMessage and get an item from it:

Adform.AdMessage.build({
    domain: dhtml.getVar('domain', 'https://track.adform.net/banners/')
}).getItems([dhtml.getVar('gid', 0)], function (error, items) {
        if (!error && items && items[0]) {
            console.log(items[0]);
            // renderBanner(items[0]);
        } else {
            let item = {
                'travelDestination': 'Thailand',
                'image': 'https://images.com/thailand.jpg'
            }
            // renderBanner(item);
        };
    });

Or simply use getDefault:

Adform.AdMessage.build({
    domain: dhtml.getVar('domain', 'https://track.adform.net/banners/')
    }).getDefault(function (error, item) {
        if (!error && item) {
            console.log(item);

            /* will return something like:
            $id: 0
            $link: ""
            $name: "default"
            $pdata: ""
            travelDestination: "Thailand"
            image: "https://s1.adform.net/banners/images/1234/1234/1234.jpg"
            */

            // renderBanner(items[0]);
        } else {
            let item = {
                'travelDestination': 'Thailand',
                'image': 'https://images.com/thailand.jpg'
            };
            // renderBanner(item);
        };
    });

For product targeting banners, instead of getPage, use getItems and get item by gid (group id). Or get the default item with getDefault. For more information, see Build Product Targeting Banners.

You also don't need dcoEngineId as there are no product targeting rules. All the values can be default ones, so in Adform.Admessage.build you just need to define the domain if you want the banner to work on a local machine (if you are working in Studio, you can just pass an empty object).

In else statement, hardcode some values:

let item = {
    'travelDestination': 'Thailand',
    'image': 'https://images.com/thailand.jpg'
}
// renderBanner(item);

This allows the building of a banner on a local machine. It's also used when a banner is not uploaded to the system (or doesn't have a spreadsheet assigned). If the banner is running locally, getDefault or getItems will return an error as the banner doesn't have any "defaults" assigned to it. By defining the fallback values, you can still see what the banner looks like. It also allows for agreeing on variable names.

The same method also works for product targeting banners, if, for example, you haven't synchronized the advertiser's data with Adform yet (but you have to start working on the banner itself).

Tip for Different-Sized Banners

If you are building multiple sizes of the same banner, it's a good idea to make variables more flexible, and adjustable depending on banner size.

Imagine having a spreadsheet like this:

reportingLabel

Text:travelDestination

Thailand

Travel to Beautiful Thailand!

While a full text line would fit on 970x250 and 728x90 size banners, it would break on the 300x250 size banner. On a 300x50 size banner, the text is too long. So you should use such spreadsheet:

reportingLabel

Text:travelDestination

Text:travelDestination_300x250

Text:travelDestination_300x50

Thailand

Travel to Beautiful Thailand!

Travel to<br>Beautiful Thailand!

Thailand!

In banner's code (which is the same for all banners) you can use the following code:

Adform.AdMessage.build({
    }).getDefault(function (error, item) {
        if (!error && item) {
            console.log(item);

            /* will return something like:

            $id: 0
            $link: ""
            $name: "default"
            $pdata: ""
            travelDestination: "Travel to Beautiful Thailand!",
            travelDestination_300x250: "Travel to<br>Beautiful Thailand!",
            travelDestination_300x50: "Thailand!",

            */

            renderBanner(item);
        } else {
            let item = {
                travelDestination: "Travel to Beautiful Thailand!",
                travelDestination_300x250: "Travel to<br>Beautiful Thailand!",
                travelDestination_300x50: "Thailand!",
            }
            renderBanner(item);
        };
    });

function renderBanner(item) {
    document.body.innerHTML = `${item[`travelDestination_${innerWidth}x${innerHeight}`] || item.travelDestination}`;
}

So in renderItem you can use either default travelDestination or banner size specific. It allows to optionally fill in the spreadsheet for a specific size.

For example, a 300x50 size banner will only show "Thailand" while a 970x250 or a 728x90 size banner will show the default common message. The same JavaScript code can be used for all banner sizes.

Was this article helpful?

/
How we can make it better?

Thank you for your feedback!