From September, Flash will no longer be supported by Chrome. Prepare for the shift towards HTML5 by visiting our Flash to HTML5 help page

Check it out!

Advanced Dynamic Ad Setup

  • Map Spreadsheet Variables

    Specific column (variable) names in versions spreadsheet are used in a banner's code. Imported versions data is transferred to a dynamic banner spots once banner and versions are included in the same dynamic ad setup. There are specific spreadsheet rules and requirements that must be followed in order to successfully map version and dynamic ad variables. For more details see here (system login required).

    Define Dynamic Ad Variables

    Versions columns (variables) can be divided into four main categories: Version Settings, Reporting, Creative, and Targeting. In a banner code, you should rather use creative type variables; it is not recommended to use reporting label, macros or retargeting variables.

    Variable names in a banner code must be the same as in the spreadsheet (names are case sensitive).

     

    Banner variable names for TextGraphic and Landing page variables may vary but it is advised to add semantic variable name meaning, e.g. instead of "t1" use "text_1" or "header_text". Variable amount is limited to 100.

    Asset name in the spreadsheet must be exactly the same as the name that shows up when the asset is imported into the system. 

     

    Landing pages can be added to every single version. It is recommended that the name of a landing page variable would meet clickTAG variable format, e.g. clickTAG, clickTAG2, etc., to ensure that later it is used correctly in banners source code.

  • Dynamic Ads Helper

    Description

     

    Dynamic Ads Helper is a contribution library script that allows you to match and fill dynamic banner elements with content data.

     

    Methods

     

    addText()

    Adform.DynAdsHelper.addText(id, name);
    Parameters
    Name Type  Description
    id String  Id of the HTML element that accepts dynamic content.
    name String Name of the column in the spreadsheet. 
    Description

    Replaces the contents of the HTML element with the text value from the spreadsheet. Method uses innerText() under the hood so HTML is not interpreted.

    addImage()

    Adform.DynAdsHelper.addImage(id, name);
    Parameters
    Name Type Description
    id String Id of the HTML <img> element that accepts dynamic image.
    name String Name of the asset column in the spreadsheet.
    Description

    Replaces the source of the image with dynamic asset from the spreadsheet.

    autoWire()

    Adform.DynAdsHelper.autoWire();
    Description

    If the id of the element matches the column name in the spreadsheet, autoWire method automatically pushes text and image values to the HTML elements. 

    setDemoData()

    Adform.DynAdsHelper.setDemoData(demoData)
    Parameters
    Name Type Description
    demoData Object

    Data object where the keys are column names and values - dynamic values. For example: 

    { text_field: 'Demo Text', image_field: '/images/demoImage.png'}
    Description

    setDemoData() should be called before autoWire(), addText(), and/or addImage() methods. Images should be stored in the banner assets or image links should be absolute path to the image. 

    getVar()

    Adform.DynAdsHelper.getVar(name, callback)
    Parameters
    Name Type Description
    name String Name of the column in the spreadsheet.
    callback Function Function that receives the dynamic value as the only parameter.
    Description

    Example usage: 

    Adform.DynAdsHelper.getVar('text_field', function(value) {
      console.log(value);
    });
    

     

    getVars()

    Adform.DynAdsHelper.getVars(callback)
    Parameters
    Name Type Description
    callback Function Function that receives an object, containing all dynamic values as the only parameter.
    Description

    Example usage: 

    Adform.DynAdsHelper.getVars(function(data) {
      console.log(data);
    });
    

    addDataTransformPlugin()

    Adform.DynAdsHelper.addDataTransformPlugin(plugin)
    Parameters
    Name Type Description
    plugin Function Function that receives version data as the first parameter and callback as the second parameter. The callback receives transformed data as a single parameter. Callback should always be called inside the plugin function. 
    Description

    Example usage: 

    Adform.DynAdsHelper.addDataTransformPlugin(function(data, callback){
      data.text_field = data.text_field.toUpperCase();
      callback(data);
    });
    

    Multiple data transform plugins can be registered. They are called in order of registration. 

    Usage

     

    First, add the Helper script to the head tag of the banner's HTML file:

    <script src="//s1.adform.net/banners/scripts/components/Adform.DynAdsHelper.js"></script>

     

    In the body tag, create all dynamic elements of the banner:

    <div id="text_field1">Empty...</div>
    <div id="text_field2">Empty...</div>
    <div id="text_field4_manual">Empty...</div>
    <img id="img_field" width=48 src="" />
    

     

    Then, also in the body tag, insert the auroWire script into the banner's code: 

    <script>
    Adform.DynAdsHelper.autoWire();
    </script>
    

     

    the autoWire script will dynamically fill in texts and define image sources from the versions' spreadsheet. For this to happen, for each dynamic element id there must be an identical content element id (column name). For example, if you have a dynamic element id="text_field" in your Ad, you must have a column named text_field1 in the versions' spreadsheet.

    In cases when some dynamic element id has no match, or you want to fill in some data manually, add these scripts for text and image element: 

    <script>
    Adform.DynAdsHelper.addText('text_field4_manual', 'text_field4');
    Adf.dynads.helper.addImage('img_field', 'img_field');
    </script>
    

     

    Where the first value in the brackets (as 'text_field4_manual' in the example) is a dynamic element ID, and the second value (as 'text_field4' in the example) is the content you want to add. For text elements, enter the text itself and for image elements, provide the image source file.

     Local testing

     

    To test the dynamic banner locally, add demo data to the banner's code:

    <script>
            
            // demo data for local testing
            var demoData = [
                {
                    'text_field1': '01',
                    'text_field2': '02',
                    'text_field4': '0d',
                    'img_field': 'https://site.adform.com/build/ddc8af9602d2a029e0155f6a5b198155.png'
                }
            ];
    
            Adform.DynAdsHelper.setDemoData(demoData);
    </script>

     

    For each content element id (as 'text_field1' in the example), provide the text if it is a text element (as '01' in the example) or image source file if it is an image element. Remember that content element ids have to match dynamic element ids or data has to be filled in manually in addText and addImage scripts if there's no id match.

    Demo data has to be set before the autoWire script. 

     

  • Dynamic Ads Advanced Cases

    It is advised to start building a dynamic ad with the banner sample provided (see here). Inside the sample, you will find the banner's HTML source, JavaScript file and image assets.

    You can also use Adform Studio Builder to create dynamic ads. However, testing is only possible after uploading the dynamic ad to the platform. 


    HTML file must have a DHTML library included in a head tag:

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

    In a body tag, it is possible to create any divs and add any static information you need. It is important to leave <div id="message"></div> element as dynamic version part is inserted into it. Code sample:

    <div id="wrapper" class="wrapper">
    	<div id="message"></div>
    		<div id="default">
    		<h2>Dynamic Content Banner</h2>
    			<p>Refresh to see another AdMessage Ad dimensions: 300x250px<br>
    				<span id="logo"><img src="logo.png" style="border:none;" /></span>
    			</p>
    		</div>
    </div>

    A JavaScript code is used for data parsing and version forming. Dynamic version part is formed using the Mustache script:

    <script type="text/mustache" id="admessage">
                {{#products}}
    				<a class="link" href="{{clickTAG}}" target="{{target}}">
    					<img src="{{image}}" />
    					<p style="color:#{{color}}">{{admessage_title}}</p>
    				</a>
                {{/products}}
    </script>

    Variables like {{image}}, {{color}}, {{admessage_title}}, etc. will be filled with values from versions data and can be easily changed in Adform system at any time. Note that variable names should be exactly the same as they are predefined in the spreadsheet, otherwise the banner will not find a variable value to display. A tip – if you use HTML coded characters (like <br/>, <strong>, etc.) in variable value, then you may render those correctly using the triple brackets in Mustache script, e.g., {{{variable_name}}}. 

    To test the banner, enter an actual static value from the versions list into the variable {{admessage_title}}. Dynamic value has to be returned once you upload your banner into the platform because the banner is supposed to change content depending on versions.

    dhtml.adMessage = Adform.AdMessage.build({
           cid: dhtml.getVar('cid', 0),
           tid: dhtml.getVar('tid', 0),
           domain: dhtml.getVar('domain', 'http://track.adform.net/banners/'),
           rotseqno: dhtml.getVar ('rotseqno', 0),
           clickTAG: dhtml.getVar('clickTAG', 'http://www.adform.com/'),
           pageSize: 1,
        });

    When the banner is uploaded to Adform system, the values cid, tid, domain, clickTAG... of the predefined variables are received from the system. 

     

    Using the following command, Mustache script will be filled with the particular version values from the spreadsheet. 

    dhtml.adMessage.getItems([dhtml.getVar('gid', 0)], function (err, items, info) {
      if (err) {
        // Handle AdMessage service error
        dhtml.addClass(dhtml.byId('wrapper'), 'error');
        dhtml.byId('wrapper').innerHTML = err.message;
      } else {
        dhtml.byId('message').innerHTML = dhtml.mustache('admessage', {
        products: items[0], 
        target : dhtml.getVar('landingPageTarget', '_blank'),
     clickTAG: dhtml.getVar('clickTAG', 'http://example.com'),
        });
      }
    });

    Once the banner is created, it must be assigned to the Dynamic Ad setup together with a Versions list.

    If you wish to use multiple clickTAGs, a clickTAG variable must be in the Versions list, otherwise, it will not work.