API DocsKnowledge BaseSystem StatusContact SupportContact Sales
Knowledge Base

Modifying the Ad Code

Suggest Edits

Serving Multiple Ad Sizes in One Placement

You can modify the last number of the ados_add_placement() function to serve multiple ad sizes in a slot. For instance:

ados_add_placement(23, 6872, "azk66721", [5,4,6])

This looks for an ad to show in any of those sizes (300x250, 728x90, 160x600) and resizes the div accordingly.

To learn which numbers your ad sizes are, generate ad code for those sizes first. Then, copy the numbers into a single ados_add_placement() line when you add the ad tags to your page. Be sure to separate the numbers by commas, and contain them in brackets.

Refreshing the Ad Code

To reload your ads or refresh after the page has already loaded, add .setRefresh() to the ados_add_placement function. Inside the parentheses, put the number of seconds before the ad is to change to a new ad. In the example below, "15" is 15 seconds:

ados_add_placement(650, 16803, "azk70681", 6).setZone(3055).setRefresh(15);

The default refresh rate is 10 seconds, and the minimum refresh rate is 1 second. If you enter 0, null, or a number less than 1, we will refresh every 10 seconds.

Note: if you only wish to refresh and ad one time after 15 seconds, add false parameter to setRefresh, which says do not repeat forever.
ados_add_placement(650, 16803, "azk70681", 6).setZone(3055).setRefresh(15,false);

Refreshing Ad Placements Conditionally

You may want to refresh certain placements in your ad request but not others. To do this, use additional JavaScript and specify isRefresh to true as in the example below:

<html>
    <head>
        <script type="text/javascript">
              var protocol = document.location.protocol == "https:" ? "https" : "http";
              var z = document.createElement("script");
              z.type = "text/javascript";
              z.src = protocol + "://static.adzerk.net/ados.js";
              z.async = true;
              var s = document.getElementsByTagName("script")[0];
              s.parentNode.insertBefore(z,s);
        </script>
        <script type="text/javascript">
            // By default, "isRefresh" is set to "false" below. This means that by default, the ad won't refresh. "window.top.isRefresh = true;" needs to be in the <body> script tag below (see my comment below) in order to get the ad to refresh.
            var isRefresh;
            (function() {
                // timesToRun is the number of refresh attempts which will be made per page load. Set it to whatever you need.
                var timesToRun = 100;
                // secondsPerRun is the interval between ad refresh attempts. The below line will currently attempt a refresh every two seconds. Set this to whatever you need.
                var secondsPerRun = 2;
                var timesRun = 0;

                var interval = setInterval(function(){
                    timesRun += 1;
                    if(timesRun === timesToRun){
                        clearInterval(interval);
                    }
                    ados.run.push(function() {
                        // if "isRefresh" is set to "true", execute an ad refresh. If otherwise ("false"), do nothing.
                        if (isRefresh === true)
                            {
                                document.getElementById("azk1").innerHTML = "";
                                //copy/paste placement(s) you want refreshed from above.
                                // Notice "azk1". This value must match the <div id> below in the body.
                                ados_add_placement(9701, 321695, "azk1", 4);
                                // Feel free to comment out or delete the below console log if not needed.
                                console.log("Loading: " + timesRun);
                                ados_load();
                            }
                    });
                }, secondsPerRun * 1000); 
            })();
        </script>
    </head>
    <body>
        <div id="azk1">
            <script>
                // set "window.top.isRefresh" to "false" in order to ensure an ad won't refresh. Set it to "true" if you do want it to refresh.
                window.top.isRefresh = true;
                console.log(window.top.isRefresh);
            </script>
        </div>
    </body>
</html>

Refreshing Companion Ads

To refresh companion ads, modify the following refresh code and add it below your ad code.

<script type="text/javascript"> 
setInterval(function(){ 
document.getElementById("azk1111").innerHTML = ""; 
document.getElementById("azk2222").innerHTML = ""; 
document.getElementById("azk3333").innerHTML = ""; 
ados.run.push(function() { 
ados_add_placement(1234, 56789, "azk1111", 766); 
ados_add_placement(1234, 56789, "azk2222", 6); 
ados_add_placement(1234, 56789, "azk3333", 6); 
ados_load(); 
});},5000); 
</script>

The ados_add_placement lines should be copy and pasted from the original ad code. The getElementById identifications must match the <div> IDs for the ads being refreshed. The 5000 denotes the number of milliseconds between each ad refresh.

Including Keywords

To serve a flight that is targeted to certain keywords, add the keywords after the ad placement code with ados_setKeywords();

ados_add_placement(650, 16803, "azk70681", 6).setZone(3055); ados_setKeywords('dodge, truck, SUV');

Separate each keyword with a comma, and enclose in single brackets.

Adding ados_setKeywords(); to your ad tags will set keywords for the entire ad request (which includes all of the placements called in the ad tags). This means that if you set a keyword for one placement, all of the placements in the tags will also be set for that keyword. To target a specific placement with a keyword, use multiple sets of ad tags, or add ados_load(); after each placement you need to set with a keyword. To set no keyword at all, use ados_setKeywords(""); after the placement.

To add keywords to Email ad code, append the keywords to the end of the <img> tag, using ?keywords=:

<img border="0" src="https://e-<networkId>.adzerk.net/s/14889/0/4/89011487?keywords=keyword1,keyword2,keyword3"; />

Renaming Placement

You can rename the div generated in the ad code, but the new name must match in both the script section and the <div> ID:

ados_add_placement(650, 16803, "above_the_fold_160", 6).setZone(3055);

Serving Specific Campaigns, Flights, or Creatives

Below are instructions on how to manually serve specific campaigns, flights, or creatives. You can also use generate ad code automatically by selecting "Generate Ad Code" in the Tools dropdown next to a creative, flight, or campaign.

To serve specific campaigns, flights, or creatives:

  1. Generate 3rd Party Ad Server code
  2. Find the ID of the campaign, flight, or ad you want to serve. You can find these in the Campaigns --> Campaigns or Flights or Ads tabs
661
  1. Modify the ad code to set the ID you want to serve
  • For a campaign, include .setCampaignId()

ados_add_placement(650, 16803, "azk70681", 6).setZone(3055).setCampaignId(7883);

  • For a flight, include .setFlightId()

ados_add_placement(650, 16803, "azk70681", 6).setZone(3055).setFlightId(17814);

  • For a creative, include .setFlightCreativeId()

ados_add_placement(650, 16803, "azk70681", 6).setZone(3055).setFlightCreativeId(29052);

Serving Multiple Zones in One Placement

You can modify a placement to make it eligible to serve ads targeted to multiple zones:

ados_add_placement(650, 16803, "azk70681", 6).setZone(3055,3056,3057).setCampaignId(7883);

Use a comma to separate the zone IDs.

📘

If a flight without zone targeting is served by a placement with multiple zones, we will only record the impression and click etc. for the first zone listed in the placement.

Serving to Secure Pages

❗️

You should always use https to call Kevel's APIs and ad code. Older ad codes may not use https - those should be updated to use https only.

Ad code generated after February 3, 2020 serves to secure pages (https) only. Ad code generated before then should be updated to use https.

Kevel's older Standard ad code automatically chose which protocol to use, so as long as you load the ad code from an https page, you won't need to modify anything.

🚧

If older Kevel Standard code is loaded from an http page, it will stop working. Instead, load the ad code via https.

If you're using Kevel's Synchronous, Email, or 3rd Party Ad Server ad code, you will need to make one simple change. After generating ad code, you'll see the ad request is in http:// format, like this:

<script type="text/javascript" src="http://static.adzerk.net/ados.js"></script>

or

<a href="http://engine.adzerk.net/s/redirect/15404/0/4/41392450">

Change this request to:

https://s.zkcdn.net/ados.js

and your ads will serve correctly.

Tracking Clicks on 3rd Party Ad Servers

To track clicks on a third-party server (like DFP), insert the server's click tracking macro in the .setRedirectURL() field in the 3rd Party Ad Server type ad code:

ados_addInlinePlacement(1613, 15404, 4).setRedirectUrl('-optional-click-macro-').loadInline();

Enclose the click tracking macro within the single quotation marks:

ados_addInlinePlacement(1613, 15404, 4).setRedirectUrl('%%CLICK_MACRO_HERE%%').loadInline();

Overriding the Userkey (USERDB)

By default, Kevel's ados.js ad tags will assign a random, unique UserKey to each user making a request. To pass in a permanent UserKey, you will need to add the following function to the ad call:

ados_setUser("unique user ID");

For example:

javascript var ados = ados || {};
ados.run = ados.run || [];
ados.run.push(function() {
ados_add_placement(9709, 439787, "azk32638", 20);
ados_setUser("ue1-29thd03");
ados_load();

Overriding the User Agent String

Instead of using a browser's default user agent string, you can pass in a user agent of your choice:

ados_setUserAgent("full user agent string");

For example:

javascript var ados = ados || {};
ados.run = ados.run || [];
ados.run.push(function() {
ados_add_placement(9709, 439787, "azk32638", 20);
ados_setUserAgent("Lynx/2.8.1pre.9 libwww-FM/2.14");
ados_load();

Overriding the IP Address

You can override the IP address of the request. Note that the IP address must be valid, or else the request will fall back to the address of the originating server.

ados_setIp("valid IP address");

For example:

javascript var ados = ados || {};
ados.run = ados.run || [];
ados.run.push(function() {
ados_add_placement(9709, 439787, "azk32638", 20);
ados_setIp("212.77.0.223");
ados_load();

Setting Accessibility Tags

You can set custom accessibility tags in the ad response by using the ados_setAccessibility function. This can write:

PropertyDescriptionDefaultExample
iframe_titleThe ad iframe's titleemptyad
iframe_langThe ad iframe's language attributeemptyen
impression_pixel_altAlt text for the impression pixel (i.gif)emptyad

👍

The default values for the accessibility attributes are empty. Setting accessibility tags creates new values instead of overriding them.

For example: 

javascript var ados = ados || {};
ados.run = ados.run || [];
ados.run.push(function() {
ados_add_placement(9709, 439787, "azk32638", 20);
ados_setAccessibility({
    "iframe_title": "ad",
    "iframe_lang": "en",
    "impression_pixel_alt": "ad"
})
ados_load();

Setting Data Consent Preferences

You can set your user's data consent preferences on an ados.js request. For example, setting GDPR data tracking consent for European Union users looks like this:

ados_setConsent({gdpr: true});

For example: 

javascript var ados = ados || {};
ados.run = ados.run || [];
ados.run.push(function() {
ados_add_placement(9709, 439787, "azk32638", 20);
ados_setConsent({gdpr: true});
ados_load();

Note that GDPR consent defaults to false if it is not explicitly set to true.

🚧

GDPR consent settings use the boolean true, not the string "true".

A full list of data consent settings is found in the GDPR documentation.

Using Dynamic Site Selection

Dynamic site selection is an ad code modification that automatically sets the SiteId for the ad code based on the domain where the tags are hosted. This feature can be used two ways:

  • Dynamic site tags prevent tags from serving on unauthorized domains. If dynamic site tags are served on a page whose domain isn't a Site in the originating network, the ad call will not complete, and no ads will be served.
  • Dynamic site tags let a publisher or network with many separate Sites use the same tags across all their sites with no modifications to the ad code. Standard ad tags require a unique SiteId for every site in a network, or impression and click data will not be tracked for individual sites. Dynamic site tags will track clicks and impressions for multiple sites, while using the same ad tags for each.

To use dynamic site selection:

  1. Make sure that every domain you intend to use the tags for has been created as a Site in your network. Note that subdomains will be counted as a separate site.
  2. Generate ad tags for the intended Ad Size and Zone on the Ad Code page.
  3. To prevent the tags from serving to unknown domains, modify the SiteId (the middle number in the ados_add_placement(); function) as 0, or, modify the ados_addInlinePlacement(); function in the 3rd Party Ad Server tags.
  4. To allow the tags to fallback to a default site if the domain is unknown, modify the placement function with the siteId of the fallback site. Any clicks and impressions from the unknown domain will be recorded as coming from the default site.
  5. Append the method enableDynamicSiteSelection() to the end of the function.

Once modified, your function will look like this:

ados_add_placement(1613, 0, "azk96446", 1).enableDynamicSiteSelection();

Or:

ados_addInlinePlacement(1613, 0, 1).enableDynamicSiteSelection().loadInline();

Your tags are now ready to be used on a page. If you're using 3rd Party Ad Server tags, make sure the .loadInline(); method is the last on the function to enable the ad to load.

Updated 7 months ago