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

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

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

    <script src="//s1.adform.net/banners/scripts/components/contrib/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 autoWire 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_field1" 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 elements:

    <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, 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.