Creating a Dynamic HTML 5 Ad

Prev Next

What is a Dynamic Ad?

Dynamic Ads allow an advertiser to serve dynamic content in an ad based on specific criteria available in real-time. For example, if you are a software company targeting the Automobile industry and the Oil & Gas industry, then you may want to show different background images in your banner ad. This can be achieved using Dynamic Ads. Another goal that can be achieved using Dynamic Ads is personalization. You can introduce dynamic text in your ad and depending upon the viewer’s company, you can customize specific words or the message in the creative.

How do Dynamic Ads Work?

Let’s take the above example of serving contextual banner depending on the industry of the account viewing the ad. In such case, you need to specify the image that is served to a viewer from a particular industry. The industry information can be accessed real-time using 6sense Company Detail API. As soon as the Dynamic Ad wins an impression, 6sense API can be used to fetch the industry of the company that the user belongs to. The Ad can then determine the banner image based on the mapping specified in HTML5 code.

What is the Company Identification API?

6sense provides the API endpoint, which can be used to get company  identification of the user to whom an Ad is served. To authenticate the API you need an authorization token provided by 6sense CSM. The following section will explain the usage of Company Identification API for creating Dynamic Ads. You can read more about the Company Identification API here.

How do I create a Dynamic Ad?

In order to serve dynamic content in an ad, you need to create an Ad type “Dynamic HTML5” on the 6sense platform. Dynamic Ads are essentially modified HTML5 ads that include dynamic content. Below are some personalization examples.

How do I test the Dynamic Ad?

Once the HTML5 Ad is created, open index.html file in your browser and it will show the Ad as per the defined mapping. If you need to test various personalizations of the Ad, send us the sample accounts that are mapped to different images and we shall send you corresponding IPs. You should use the provided IP address in the “X-Forwarded-For” header in your API call.

Note: Please remove this testing code snippet before setting the tag live.  

function init() {
	...
	xhr.setRequestHeader("Authorization", "Token <YOUR_TOKEN_HERE>");
	xhr.setRequestHeader("X-Forwarded-For", "<IP_ADDRESS>"); // To test your HTML5 ad uncomment this line and put the appropiate ip address for the account you want to test
	...
}

Example 1: Image and Landing Page Personalization

Download the sample file (open link and click download in the top left)

Steps for creating HTML5 Dynamic Ad

Step 1 – Create HTML5 Ad: Create a HTML5 Ad as per the guidelines. Please check the documentation to understand HTML5 Ads Prerequisites.

Step 2 – Add multiple banner images and define serving criteria: Include multiple banner images in your zip file such that your HTML file can access them. Subsequently, define the mapping of the images with different criteria. Referring to our Dynamic HTML5 sample file, our goal is to serve images dynamically based on the company identification of the user. Correspondingly, the mapping includes: “USA_1.png” served to the user from 6sense US and “India_1″.png” served to the user from 6sense India. To identify the user’s company, you need to use the Company Detail API.

var mappings = [ 
{ 
    // Personalization Example 1: 
    url: 'USA_1.png', //This is the url of image that needs to be shown when all criteria match. 
    clkUrl: "https://6sense.com/abm/example-landing-page1", // Custom landing page for everything that matches the criteria defined below for personlization 

    name: ['6sense'], // criteria 1: Company name should match this value 
    country: ['united states'] // criteria 2: Company country should match this value 
  }, 
  { ... }, 
  ];

Note: You can use any criteria from the Company Detail API response in your mapping to achieve your specific targeting goals. For example, serve specific creatives based on company name, industry, country of the account, revenue range of the account etc.

Step 3 – Add Default Image: Include default image in your .zip file along with your multiple banner images. Default image is a banner image that will be served to the user in the following scenarios:

  • When the ad served to a user whose company identification do not match with any of the defined mappings. When the company detail API fails or receives invalid results from the API.

We recommend including a default image to ensure that your impressions don’t go waste in case of the above scenarios.

You can define default image path in a variable, for example in the code below, where the variable name is defaultImage and it assigns an image path Global_1.png.

// This is default image, which will be shown if there no match in mapping. 
var defaultImage = 'Global_1.png'; 

Note: To understand how to use default image you can check out the below section where you can see how the default image is used in calling Company Detail API or in renderImage function.

Step 4 – Render Image using Company Detail API: In the HTML5 Ad, call a function that uses company detail and render the appropriate image based on mapping criteria.

Referring back to our sample HTML5 .zip file, it includes a code to understand how to use the Company Identification API. 

function init() { 
  window.dynamicContent = document.getElementById('content'); // The div to replace the image into. 
  window.clickUrl = undefined; // the global variable to store the url from mapping. 'undefined' during init process. 
  window.companyName = undefined; // the global variable to store the campany name from mapping. 'undefined' during init process. showImage(loader); // Showing loader image while we wait for the response from company identification api. 
  var xhr = new XMLHttpRequest(); 
  xhr.withCredentials = true; 
  xhr.addEventListener("readystatechange", function () { 
    addListeners(); // Adding click listener to content; to handle click redirects 
    if (this.readyState == 4) { // After we get the response. 
      if (this.status !== 200){ // if the response is failure; i.e. non 200 
        // show default image if we don't get proper response 
      showImage(defaultImage); 
    } else { 
      // get the success response 
        res = JSON.parse(this.responseText); // this is how you parse the response from company identification api 
               renderImage(res.company); // passing the company identification to renderImage function, described below 
      }
    } 
  }); 
  xhr.open("GET", "https://epsilon.6sense.com/v3/company/details"); // The actual call made to company identification api xhr.setRequestHeader("Authorization", "Token <YOUR_TOKEN_HERE>"); // The company identification api-token (provided by 6sense) goes here. 
  // xhr.setRequestHeader("X-Forwarded-For", "<IP_ADDRESS>"); To test your HTML5 ad uncomment this line and put the appropiate ip address for the account you want to test 
  xhr.timeout = 5000; // ideal to wait for 5 seconds 
  xhr.send(); // The call starts here. }

Note: Call the Company Detail API on load of your index.html, please refer above code and sample zip file. In the code above, renderImage function gets called after the successful API response. renderImage uses response from the Company Identification API to render appropriate image based on the mapping criteria defined in Step 2 above.

Below code explains how to use renderImage function.

function renderImage (company) { 
  var userCountry = company.country.toLowerCase(); // get the country of company from company identification api 
  var userCompanyName = company.name && company.name.toLowerCase(); // get the name of company from company identification api 
  var imageUrl = defaultImage; // defualt image url, defined in index.html 
  for (var index = 0; index < mappings.length; index++) { // Loop over the mapping and see if any of the item matches with response 
    var mappingObj = mappings[index]; // get the mapping item from mappings defined in index.html 
    var url = mappingObj.url; // get the image url from the mapping item 
    var clkUrl = mappingObj.clkUrl; 
    var mappedCountries = mappingObj.country; // get the country from the mapping item 
    var mappedCompanyName = mappingObj.name; // get the name of company from the mapping item // check if user country is included in mapped countries 
    var isCountryIncluded = mappedCountries.indexOf(userCountry) > -1; // check if country from company detail api is present in mapping countries // check if user company is included in mapped company 
    var isCompanyNameIncluded = mappedCompanyName.indexOf(userCompanyName) > -1; // check if name from company detail api is present in mapping names if (isCountryIncluded && isCompanyNameIncluded) { // if both of the are present 
      clickUrl = clkUrl; 
      companyName = userCompanyName; // store the user matched company name 
      imageUrl = url; // store the url break; // break the loop, as we found our match. 
    } 
  } 
  // show the image by calling 
      showImage function showImage(imageUrl); 
  // Note: Here imageUrl is set to defaultImage, at the beginning of the function. 
  // if the for loop update the variable, that image will be shown 

Example 2: Company Name and Landing Page Personalization

Download the sample file (open link and click download in the top left)

Steps for creating HTML5 Dynamic Ad

Step 1 – Create HTML5 Ad: Create a HTML5 Ad as per the guidelines. Please check the documentation to understand  HTML5 Ads Prerequisites.

Step 2 – Add Company Name and define landing page url based on Company:  Define the mapping of the company names with their respect landing pages. Referring to our Dynamic HTML5 sample file, our goal is to replace company name on the Ad and click URL based on company identification of the user. Correspondingly, the mapping includes:
“UW Medical” served to the user from UW Medical company,
“OHSU” served to the user from OHSU company, etc. To identify the user’s company, you need to use the Company Detail API. 

var companyUrlMapping = { 
    "UW Medical": "https://www.uwmedicine.org/", // Key is used as custom text and value as the custom click URL based on matched company 
    "OHSU": "https://www.ohsu.edu/", 
    "Virginia Mason": "https://www.virginiamason.org/", 
    "Seattle CCA": "https://www.seattlecca.org/", // add your additional personalization here in the format 
    // [Company Name]: "Click URL" 
};

Note: Please customize your creative appropriately to allow company name of max 22 characters for clean display. Creatives may get rejected if the text overlaps with other image components within the ad. We recommend 22 characters space for 300×250 creative size and 16 chars for 160×600 skyscraper creative.

Step 3 – Add Image: Include the ad image in your .zip file. This banner image will be served to the user with the customized company name defined in #2 above.

When the ad served to a user whose company identification match, the image is personalized with the respective company name. Example below.

mceclip0.png

When the ad served to a user whose company identification do not match or the company detail API fails or receives invalid results from the API., we show the default image without personalization.

mceclip1.png

You can define image path in a variable, for example in the code below, where the variable name is imageUrl and it assigns an image path Global_1.png.

var imageUrl = 'Global_1.png'; // this image is shown for all

Step 4 – Render Company name using Company Detail API: In the HTML5 Ad, call a function that uses company detail and render the appropriate company name based on mapping.

Referring back to our sample HTML5 .zip file, it includes a code to understand how to use the Company Identification API. 

function init() { 
  window.dynamicContent = document.getElementById('content'); // The div to replace the image into. 
  window.clickUrl = undefined; // the global variable to store the url from mapping. 'undefined' during init process. 
  window.companyName = undefined; // the global variable to store the company name. 'undefined' during init process. 
  // Showing loader 
  showImage(loader); 
  var xhr = new XMLHttpRequest(); 
  xhr.withCredentials = true; 
  xhr.addEventListener("readystatechange", function () { 
    addListeners(); // Adding click listener to content; to handle click redirects 
    if (this.readyState == 4) { // After we get the response. showImage(); 
      if (this.status === 200){ // if we get the success response 
        res = JSON.parse(this.responseText); // this is how you parse the response from company identification api 
        companyName = res.company.name; 
        var matchedMappingKey = Object.keys(companyUrlMapping).find(function (name) { 
          return name.toLowerCase() === companyName.toLowerCase(); 
      }); // match company name ignoring case from the mapping object 
      if (companyName && matchedMappingKey) { 
          clickUrl = companyUrlMapping[matchedMappingKey]; // get the custom click url from mapping 
          displayPersonalizedText(companyName); // passing the company name to add personalized company name text on top of the ad 
        } 
      } 
    } 
  }); 
  xhr.open("GET", "https://epsilon.6sense.com/v3/company/details"); // The actual call made to company identification api 
  xhr.setRequestHeader("Authorization", "Token <Insert Token>"); // The company identification api-token (provided by 6sense) goes here. 
  // xhr.setRequestHeader("X-Forwarded-For", "<IP_ADDRESS>"); To test your HTML5 ad uncomment this line and put the appropiate ip address for the account you want to test 
  xhr.timeout = 5000; // ideal to wait for 5 seconds 
  xhr.send(); // The call starts here. 
}

Note: Call the Company Detail API on load of your index.html, please refer above code and sample zip file. In the code above, displayPersonalizedText function gets called after the successful API response. displayPersonalizedText uses response from the Company Identification API to render appropriate company name based on the mapping defined in Step 2 above.

Below code explains how to use displayPersonalizedText function.

function displayPersonalizedText(userCompanyName) { 
  var companyNameEle = document.getElementById('company-name'); // the div that shows the custom text, the company name 
  companyNameEle.innerHTML = userCompanyName + ',' 
  document.getElementById('text-area').style.top = '30%' // move the text a little more down to accomodate showing company name 
}

To learn more check out our FAQ -Dynamic HTML 5.