API DocsKnowledge BaseSystem StatusContact SupportContact Sales
Knowledge Base

Modifying the Ad Code

Serving Multiple Ad Sizes in One Placement

You can modify the last argument of the ados_add_placement() function to serve multiple ad sizes in one 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 find out which numbers correspond to your ad sizes, 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. Separate the numbers with commas and enclose 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 to wait before the ad changes to a new one. In the example below, "15" means 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 want to refresh an ad only once, after 15 seconds, add a false parameter to setRefresh() so that it does not repeat:

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 set 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 the 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>

Copy the ados_add_placement lines from your original ad code. The getElementById IDs must match the <div> IDs of the ads being refreshed. The 5000 is the number of milliseconds between each 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 the list in single quotes.

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 for manually serving specific campaigns, flights, or creatives. You can also generate this 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

  3. 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, click, and similar events 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, and 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 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 need to add the following function to the ad call:

ados_setUser("unique user ID");

For example:

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:

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:

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. It can set the following:

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:

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:

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 in the GDPR documentation.

Updated 7 days ago