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 Product Targeting Ad Setup

  • Implement Tracking Points

    For Product Targeting ads to work, you have to implement tracking points on your website. Tracking points have to be configured to fire on a particular event – product view, add to basket, purchase, etc. Product Retargeting engine analyzes these fired tracking points and cookie values stored on the visitor's machine, and picks the most suitable product (ad message to display).

    Fired product ID with tracking point variables must match product ID used in data feed. If values don't match, the retargeting engine will not work as expected.

     

    Contact Adform's Site tracking team ([email protected]) for the help in building DCO Tracking Point (TP) scripts.

     

  • Create Adform's XML Template

    The data synchronization should be done between client's product feed source (XML, CSV, JSON) and the Adform's XML template. Adform XML is an XML template on Adform system that is created manually using Data Transformer tool and the data for Product Targeting banners is filled doing automatic data import (transformation). Data transformer is a powerful tool that allows user to easily convert client's data source to Adform XML structure, do imported values customizations (if needed), apply business rules or retargeting modules in just few workflow steps.

    Automatic data import synchronize products data within defined interval of time – like once a day, twice a day, every 10 or 15 minutes. Minimum update interval is 5 minutes (cannot be smaller). Using Adform Data transformer 2Gb+ files can be transformed. Know more how to work with XML Transformer tool in Adform HELP Center (system login required).

    Once the feed is created, 4 retargeting engines are enabled by default: "View recency", "Interest score", "Interest score with rotation", "Viewed category". For more information about retargeting models, please refer to this documentation page product targeting models (system login required).


    Most Common Causes of Feed Errors

    • Missing source – source has been deleted or moved from provided location, file is unavailable.
    • Forbidden source – data source access rights has been changed and Data transformer cannot reach the source, authentication or certificate update required.
    • Restricted access – sometimes Data transformer IP should be whitelisted in order to get access to client's data server. An error may occur because of IP change on our side or XML transformer IP is removed from whitelist.
    • Wrong data structure – error appears when source structure is changed and mismatching the field mapping sequence that has been set in Data transformer during first feed creation.
    • Invalid data structure – updated data source contains critical syntax errors.
    • Source inspection timeout – feed update inspection on scheduled import should take no longer than 60 seconds (source must be downloaded for inspection and validation on scheduled time). If that takes longer – timeout error appears.
    Requirements and specs for XML data source

    Collection

    • via HTTP or FTP (for FTP, login credentials must be provided)

    If you use a security certificate (HTTPS feed source), use a valid SSL certificate. If you don't, move data source to HTTP instead. You can host data sources on SFTP as well.


    XML structure validation check

    • Document must to have a root node.
    • Every node has to be closed correctly. No self closing tags (e.g. <sample/>) are supported yet. For empty nodes, please use full tag expressions, e.g. <sample>-</sample>.
    • Node name cannot contain empty spaces, e.g. <node name>info</node name> is not a valid node name.
    • HTML tags are not recommended in content, e.g. <br/> tag like in "1st line<br/> 2nd line".
    • Encoding should be UTF-8, ISO-8859-1 or Windows-1252. It's recommended to use UTF-8 in all cases.
    • Every product node (instance) must have some unique value. It can be an id, sku, number or unique string combination.
    • Product item's unique value should be no longer than 200 symbols (including spaces, commas, etc.).
    • Product item's values should not be empty. At least one character is required for each (cannot be made from space only). 
    • It is recommended that all external sources (e.g. image url, landing page url, data feed url) use secure protocols (HTTPS), if it is not for a direct campaign. For direct campaings, HTTP can be used.

    Use a unique Product ID value for each product. Product ID for a specific item in your data source and Product ID of the same item fired with DCO Tracking Point must match. This is essential in retargeting process.

    Default output variables are product_id, product_category_id, product_name, product_deeplink, product_image. This list can be filled with any other variables you need. Each variable is filled with data from XML source.

     

    Sample XML data source

    Open this link to view the structure of XML data source: http://test.adform.com/banners/mindaugas/xmls/e-shop-xml.xml

    <products>
    <product>
    <product_name>Computer 123</product_name>
    <product_id>123456</product_id>
    ...
    <product_deeplink>http://client.com/products/computer123</product_deeplink>
    <product_image>...</product_image>
    </product>
    <product>
    <product_name>Computer 456</product_name>
    <product_id>456789</product_id>
    <product_category_id>computers</product_category_id>
    ...
    <product_deeplink>http://client.com/products/computer456</product_deeplink>
    <product_image>...</product_image>
    <product>
    ...
    <products>

    Contact Adform Technical Support ([email protected]) if any issues occur.

     

    Requirements and specs for CSV data source

    Collection

    • via HTTP or FTP (for FTP, login credentials must be provided)

    CSV validation check

    • First row should be set as column (field) names.
    • Fields values should be separated with either comma (,), vertical bar (|), or semicolon (;) delimiter or TAB separated.
    • If comma (,) is used as field values delimiter and there are texts that contain commas, then text strings should be added to double or single quotes qualifier, e.g. id111,Product A,"Some text string, another word, test",http://deeeplink.com,price 11 Eur
    • Encoding should be set to UTF-8.
    • Every product node (instance) must have some unique value. It can be an id, sku, number or unique string combination.
    • Product item's unique value should be no longer than 200 symbols (including spaces, commas, etc.).
    • Product item's values should not be empty. At least one character is required for each (cannot be made from space only). 
    • It is recommended that all external sources (e.g. image url, landing page url, data feed url) use secure protocols (HTTPS), if it is not for a direct campaign. For direct campaings, HTTP can be used.

    Tip: if CSV is formed right after opening it with MS Excel you should see data values nicely filled to columns.

     

    Sample CVS data sources

    CSV file with comma delimited fields – http://test.adform.com/banners/mindaugas/csv/comma_delimited.csv

    product_id,product_name,product_category_id,product_deeplink,product_image,product_price
    id-1,Head saver,Head holders,http://dcodemo.adform.com/eshop/?product_id=1,http://files.adform.net/Banners/Stream/images/head-saver.jpg,90
    id-2,Diet belt,Clothes,http://university.adform.com/eshop/?product_id=2,http://files.adform.net/Banners/Stream/images/diet-belt.jpg,10.50
    id-3,Washing boots,Good Ideas,http://university.adform.com/eshop/?product_id=3,http://files.adform.net/Banners/Stream/images/washing-boots.jpg,30.33
    id-4,Dream pillow,Head holders,http://university.adform.com/eshop/?product_id=4,http://files.adform.net/Banners/Stream/images/dream-pillow.jpg,150.00
    id-5,Time killer,Good Ideas,http://university.adform.com/eshop/?product_id=5,http://files.adform.net/Banners/Stream/images/time-killer.jpg,9.99

    CSV file with semicolon delimited fields – http://test.adform.com/banners/mindaugas/csv/semicolon_delimited.csv

    product_id;product_name;product_category_id;product_deeplink;product_image;product_price
    id-1;Head saver;Head holders;http://university.adform.com/eshop/?product_id=1;http://files.adform.net/Banners/Stream/images/head-saver.jpg;90
    id-2;Diet belt;Clothes;http://university.adform.com/eshop/?product_id=2;http://files.adform.net/Banners/Stream/images/diet-belt.jpg;10.50
    id-3;Washing boots;Good Ideas;http://university.adform.com/eshop/?product_id=3;http://files.adform.net/Banners/Stream/images/washing-boots.jpg;30.33
    id-4;Dream pillow;Head holders;http://university.adform.com/eshop/?product_id=4;http://files.adform.net/Banners/Stream/images/dream-pillow.jpg;150.00
    id-5;Time killer;Good Ideas;http://university.adform.com/eshop/?product_id=5;http://files.adform.net/Banners/Stream/images/time-killer.jpg;9.99

    CSV file with comma delimited fields and texts with commas – http://test.adform.com/banners/mindaugas/csv/comma_delimited_texts.csv

    product_id,product_name,product_category_id,product_deeplink,product_image,product_price
    id-1,"Head saver, product",Head holders,http://university.adform.com/eshop/?product_id=1,http://files.adform.net/Banners/Stream/images/head-saver.jpg,90
    id-2,"Diet belt, nice item",Clothes,http://university.adform.com/eshop/?product_id=2,http://files.adform.net/Banners/Stream/images/diet-belt.jpg,10.50
    id-3,"Washing boots, good idea",Good Ideas,http://university.adform.com/eshop/?product_id=3,http://files.adform.net/Banners/Stream/images/washing-boots.jpg,30.33
    id-4,"Dream pillow,sweet dreams",Head holders,http://university.adform.com/eshop/?product_id=4,http://files.adform.net/Banners/Stream/images/dream-pillow.jpg,150.00
    id-5,Time killer,Good Ideas,http://university.adform.com/eshop/?product_id=5,http://files.adform.net/Banners/Stream/images/time-killer.jpg,9.99

    Contact Adform Technical Support ([email protected]) if any issues occur.

     

    Requirements and specs for JSON data source

    Collection

    • via HTTP or FTP (for FTP, login credentials must be provided)

    JSON structure validation check

    • Encoding should be set to UTF-8.
    • Every product node (instance) must have some unique value. It can be an id, sku, number or unique string combination.
    • Product item's unique value should be no longer than 200 symbols (including spaces, commas, etc.).
    • Product item's values should not be empty. At least one character is required for each (cannot be made from space only). 
    • It is adviced to use objects as 1 level structure.
    • It is recommended that all external sources (e.g. image url, landing page url, data feed url) use secure protocols (HTTPS), if it is not for a direct campaign. For direct campaings, HTTP can be used.

    Sample JSON data source

    Open this link to view the structure of JSON data source: http://test.adform.com/banners/mindaugas/json/data.json

    {
      "products": {
        "product": [
          {
            "product_id": "id-1",
            "product_name": "Head saver",
            "product_category_id": "Head holders",
            "product_deeplink": "http://dcodemo.adform.com/eshop/?product_id=1",
            "product_image": "http://files.adform.net/Banners/Stream/images/head-saver.jpg",
            "product_price": "90"
          },
    		.....
          {
            "product_id": "id-10",
            "product_name": "Winter wear",
            "product_category_id": "Clothes",
            "product_deeplink": "http://dcodemo.adform.com/eshop/?product_id=10",
            "product_image": "http://files.adform.net/Banners/Stream/images/winter-wear.jpg",
            "product_price": "400.00"
          }
        ]
      }
    }

    Contact Adform Technical Support ([email protected]) if any issues occur.

     

  • HTML5 Banner Specifications

    Once the client‘s feed has been synchronized with Adform’s XML template, template's variables can be provided and a banner can be tested locally. Variables allow seeing converted product feed information in the Product Targeting ad locally or in Adform Studio.

    Creating Product Targeting ad is similar to creating a HTML5 banners for Dynamic Ad.

    1. Include a dhtml library and a Products component in a header element of an HTML file:
    <script>
    	var components = [
    		'Products'
    	];
    	document.write('<script src="'+ (window.API_URL || 'https://s1.adform.net/Banners/scripts/rmb/Adform.DHTML.js?bv='+ Math.random()) +'"><\/script>');
    </script>
    1. Build a connection between Adform data template and the banner:
    dhtml.adMessage = Adform.AdMessage.build({
                    cid: dhtml.getVar('cid', 28538),
                    tid: dhtml.getVar('tid', 12388),
                    dcoEngineId: dhtml.getVar('dcoEngineId', 2),
    				bn: dhtml.getVar('bn', 0),
                    domain: dhtml.getVar('domain', 'http://track.adform.net/banners/'),
                    clickTAG: dhtml.getVar('clickTAG', 'http://www.adform.com/'),
                    pageSize: 4
                });

    cid, tid, domain and clickTAG values are received from the system when the banner is uploaded to Adform's platform. When testing the banner locally, in HTML5 Studio or banner preview, use dcoEngineId to load data from feed.

    Once the client’s product feed is synchronized with Adform’s template, different cid and tid values will be provided.

     

    1. Use setupProducts function to define the properties of Product Targeting ad:
    dhtml.setupProducts({
       container: dhtml.byId('productsContainer'),
       layout: dhtml.getVar('layout', 'horizontal'),
       pageSize:   parseInt(dhtml.getVar('pageSize', 3), 10), //How many products to show
       stepSize:   parseInt(dhtml.getVar('stepSize', 1), 10), //How many products to scroll
       perItem:    parseInt(dhtml.getVar('perItem', 1), 10), //There can be several products shown per one item
       duration:   parseInt(dhtml.getVar('duration', 500), 10), //Animation speed
       autoScroll: parseInt(dhtml.getVar('autoScroll', 1), 10) //If autoscroll should be enabled
     }, productsCallback)

    This function defines how many products are showed at once, the scroll step, and whether animation should be enabled.

    1. Form dynamic template for product targeting ad with the Mustache script:
    <!-- Dynamic template for single Product Item -->
            <script type="text/mustache" id="item">
                {{#products}}
                  <div class="product">
                    <a href="{{$link}}" target="{{target}}" class="product-link">
                        {{#product_image}}
                            <div class="product-photo photo">
                                <img src="{{product_image}}" alt="{{product_id}}">
                            </div>
                        {{/product_image}}
                        <p class="product-label product-name">{{product_name}}</p>
                        <p class="product-label product-category">{{product_category_id}}</p>
                        <p class="product-label product-price">{{product_price}}</p>
                    </a>
                  </div>
                {{/products}}
            </script>

    Values {{product_image}}, {{product_price}}, {{product_name}} etc. will be filled from the products template.

    Please leave {{$link}} as href value reference. Do not change it to {{product_deeplink}}. {{$link}} will inherit product deeplink value automatically after clickthrough redirect is made.

     

    1. Use productsCallback function to fill in the Mustache template and to handle the product scrolling. For cases when there is an outage in service from the recommendation engine (a 404 or a malformed response) the function has a built-in alternate logic to display fallback asset or any static content.

    Update function code to display proper fallback prior to launching the ad to go live.

     

    function productsCallback(error, productsInstance) {
      if (error) {
    	//display fallback asset (or static content) if there were an outage in product recommendation service 
    	dhtml.addClass(dhtml.byId('wrapper'), 'static');
    		var image = dhtml.getAsset(1) || 'assets/logo.png';
    		static_content = '<div>This is a falback message<br><img src='+image+' alt="fallback image"></div>';	
    	dhtml.byId('wrapper').innerHTML = static_content;	
      } else {
    	var prev = dhtml.byId('prev');
    	var next = dhtml.byId('next');
    
    	/**
    	 * itemShow event is emitted for each item that is currently
    	 * visible in the view/mask and additionally for items
    	 * that must be pre-cached, for smooth animation.
    	 *
    	 * node - HTMLElement of Products Scroller
    	 * data - loaded items from AdMessage service
    	 */
    	productsInstance.on('itemShow', function (node, data) {
    	  node.innerHTML = dhtml.mustache('item', {
    		products: data,
    		target : dhtml.getVar('landingPageTarget', '_blank')
    	  });
    	});
    
    	/**
    	 * itemHide event is emitted for each item that is not used in animation. 
    	 */
    	productsInstance.on('itemHide', function (node) {
    	  node.innerHTML = '';
    	});
    
    	/**
    	 * scroll is emitted on every scroll action.
    	 */
    	productsInstance.on('scroll', function (currentIndex, nextIndex, maxIndex) {
    	  if ( ! nextIndex) {
    		dhtml.addClass(prev, 'disabled');
    	  } else {
    		dhtml.removeClass(prev, 'disabled');
    	  }
    
    	  if ( ! (nextIndex - maxIndex)) {
    		dhtml.addClass(next, 'disabled');
    	  } else {
    		dhtml.removeClass(next, 'disabled');
    	  }
    	});
    
    	prev.onclick = function () {
    	  if (productsInstance.previous()) {
    		// Send Adform previous button press event if previous action is successful
    		dhtml.sendEvent(dhtml.PREVIOUS_BUTTON_PRESS);
    	  }
    	};
    
    	next.onclick = function () {
    	  if (productsInstance.next()) {
    		// Send Adform next button press event if next action is successful
    		dhtml.sendEvent(dhtml.NEXT_BUTTON_PRESS);
    	  }
    	};
      }
    }
  • Apply Business Rules

    Data Transformation tool enables to apply Business Rules (BR) for the feed. BR helps to filter out and recommend items for specific user more accurately.  BR controls the feed source that is parsed to the banner from ad serving recommendation engine. There are six Business rules that you can use:

    • Ad defaults – adds 100 items to feed the banner. If the recommended product count is not large enough, the first 100 products from the provided source file are stored as defaults and added to each recommendation. It is set by default, as if not, then banner would be empty until we gain some score for any item(s).
    • Ignore Interaction – define which interaction should be ignored: View, Basket or Buy. By default is Buy – if item is bought, then it is not recommended any more in a feed. This BR is enabled by default.
    • Purchased Products Only – if BR applied recommendations only show products that user purchased.
    • Ignore by TIME – ignores (or use) old tracking information – adserver checks cookie score save time and forms recommendation list from newer or older items then entered.
    • Insert Top Offers – first <top_offer>true<top_offer> should be added to data item before transformed. If this rule used, items are listed in front of recommendation parsed result.
    • Filter Top Offers – first <top_offer>true<top_offer> should be added to data item before transformed. This rule enables to use (or ignore) only those items from XML data, that has ‘true’ identifier.

    Define Top Offer in Data Source

    First, add a mark in the feed:

    <product>
    <product_id>1</product_id>
    <product_name>Head saver</product_name>
    <product_category_id>Good Ideas</product_category_id>
    <product_deeplink>http://dcodemo.adform.com/eshop/?product_id=1</product_deeplink>
    <product_image>
    http://files.adform.net/Banners/Stream/images/head-saver.jpg
    </product_image>
    <product_price>90.00</product_price>
    <top>true</top>
    </product>

    While setting up the feed with XML transformer tool, in the Field Mapping step add a custom field. Name the field as top_offer and drag top offer field (which was provided in the feed source). Then, in the Business Rules page, select either "Filter Top Offers" or "Insert Top Offers".