Ad Code Integration Guide

An ad code (also called an ad tag) is a JavaScript snippet used by the ad server to deliver and track ads on your website or application. Each advertising zone in your  Adserver.Online account has its own unique ad code that must be placed on your website to display ads.

Our asynchronous ad tags are designed for fast ad delivery and minimal impact on page performance. The ad code supports display advertising, custom targeting, conversion tracking, programmatic advertising workflows, and advanced JavaScript integrations.

Ad code example

<ins class="aso-zone" data-zone="34919"></ins>
<script data-cfasync="false" async src="https://media.aso1.net/js/code.min.js">

This code works asynchronously, so it doesn't block page loading.

Configuration

All ad codes on a page can be configured using a special JS script placed in the HEAD section:

<script> 
   var _aso = _aso || {};
   _aso.option1 = true;
   _aso.option2 = false;
</script>

Available options

  • no_ad_dups – if true, then the same banner won't be displayed on the same page more than once. False by default.
  • no_campaign_dups – if true, then the campaign (any banners of it) won't be displayed on the same page more than once. False by default.
  • tcf – if true (by default), the ad code will try to find the installed consent management platform (CMP) and retrieve the visitor's consent. If GDPR does not apply to you, you can set it to false to make ads load a little bit faster.

Click tracking in third-party ad servers

If you need to publish our ad code in a third-party ad serving system, you should use the "data-redirector" parameter to configure click tracking. Otherwise, you will see zero clicks in our reports.

You must examine third-party documentation to find needed macros.

For example, in Google Ad Manager (GAM), you should use %%CLICK_URL_UNESC%% macros.

<ins class="aso-zone" data-zone="xxx" data-redirector="%%CLICK_URL_UNESC%%"></ins>
<script data-cfasync="false" async src="https://media.aso1.net/js/code.min.js">

More info about how to publish our code in Google Ad Manager (GAM).

Third-party ad codes republishing

To republish third-party ad codes in our system, you should use HTML/JS banners.

Custom attributes

If you need to pass some custom data to the ad-serving engine for custom targeting or other purposes, you should use the following piece of JS code in the HEAD section:

<script>
   var _aso = _aso || {};
   _aso.attr = {
     tags: ["tag1", "tag2"],
     keywords: ["cats", "dogs"],
     hb_bid: 10,
     gender: "male"
   };
</script> 

Note boolean values (true/false) and multidimensional arrays are not supported.

There are reserved attribute names: refid, refid1, refid2, …, refid9. If you pass them, they will become available inside an ad server in the form of placeholders {refid}, {refid1}, {refid2}, … , {refid9}.

Note the value length is limited by max. 40 chars for refid, refid1 since they are stored to stats reports and by 255 chars for refid2 … refid9.

For example:

<script>
   var _aso = _aso || {};
   _aso.attr = {
     refid: "foo",
     refid1: "bar"
   };
</script> 

Auto refreshing

Our ad code supports auto-refreshing for banner zones. You should set the refresh interval (in seconds) in the zone's Advanced options to enable it.

Javascript API

Callbacks

Our ad code supports two JS callbacks: onload is called when an ad is displayed, and onempty when the ad server doesn't find an ad to display in a zone. These callbacks can be configured separately per ad code or as a global configuration.

Global callbacks

<script>
   var _aso = _aso || {};
   _aso.onload = function(params) {
     console.log('Ad', params.idad, 'is loaded');
   },
   _aso.onempty = function(params) {
     console.log('Zone', params.idzone, 'is empty');
   }, 
</script>

Zone callbacks

To configure callbacks, you have to change your ad code as shown:

<ins class="aso-zone" data-zone="xxx" data-onload="onloadCallback" data-onempty="onemptyCallback"></ins>

The corresponding JS function must be defined:

<script>
  function onloadCallback(params) {
     console.log("Ad loaded:", params);
  }

  function onemptyCallback(idzone) {
     console.log("No ads for zone #", idzone);
  }
</script>

Dynamic loading

The JavaScript ad tag can also be dynamically loaded in single-page applications (SPA) and other dynamic environments where ads need to be loaded programmatically.

To do that, you should call _ASO.loadAd function.

The function arguments are HTML Element ID (string), Zone ID (integer), async loading (must be true), and params (array).

Usage example:

_ASO.loadAd("el", 34919); /* HTML ID, Zone ID */

Calling with extra parameters:

_ASO.loadAd("el", 34919, true, {
  attr: {
    tags:["a", "b"],
    keywords: ["cars"]
  },
  onempty: "onEmpty",
  onload: "onLoad"
});

Custom renderer for native banners

The native banner contains data fields such as headlines, icons, etc, and appearance-related parameters such as colors, fonts, templates, etc.

By default, the native banner is rendered using a server template configured on the banner form. However, a custom JS renderer can also be configured on the client side.

First, you must modify the ad code by adding a data-renderer attribute to the ins tag. It must contain a renderer function name. For example,

<ins class="aso-zone" data-zone="xxx" data-renderer="myRenderer"></ins>

Then, you have to create the function myRenderer, which will receive data from our ad code, render it in HTML, and insert it into the page DOM.

Renderer function example:

<script>
  function myRenderer(ad) {
    var ins = document.getElementById(ad.element),
        div = document.createElement('div'),
        html;

    html = '<a href="' + ad.clickUrl + '">' + ad.data.headline + '</a>';
    html += '<img src="' + ad.data.imageUrl + '">' + ad.data.body
    div.innerHTML = html;
    ins.parentNode.replaceChild(div, ins);
  }
</script>

Dynamic loading with custom renderer:

_ASO.loadAd("el", xxx, true, {
  renderer: "myRenderer"
});

Passing parameters through an ad server to a landing page

We have a couple of scripts to help you pass parameters from the URL where ads (banners) are displayed to a landing page when a visitor clicks on them.

UTM labels

Firstly, you should add this snippet to the HEAD section of all the pages on your site:

<script src="https://media.aso1.net/js/tags/utm2attr.js"></script> 

After that, UTM labels will be available inside an ad server as special placeholders. You can insert them into the landing page URL on the ads form.

Placeholders: {refid}, {refid1}, {refid2}, {refid3}, {refid4}.

Arbitrary parameters

Firstly, you should add this snippet to the HEAD section of all the pages on your website:

<script type="text/javascript" src="https://media.aso1.net/js/tags/subid2attr.js"></script> 

After that, GET parameters t1 … t10 will become available inside the adserver as special placeholders. You can insert them into the landing page URL on the ads form.

Placeholders: {refid}, {refid1}, {refid2}, {refid3}, {refid4}, {refid5}, {refid6}, {refid7}, {refid8}, {refid9}.

Besides, you can add a special parameter to URL subid_param=xxx, for example, subid_param=subid. In this case, parameters with the names subid1 … subid10 will be extracted from the URL instead of t1 … t10. 

Please note statistics are only collected for the first two parameters (refid, refid1). Therefore, refid2 to refid9 are considered passthrough parameters, so there are no statistics on them.

Google Ad Manager (GAM)

This article explains how to publish our ad codes in Google Ad Manager.

AMP page advertising

Read how to advertise on AMP pages.

Integration demos

Summary

The ad code and JavaScript API provide a flexible way to integrate ad serving, targeting, reporting, and tracking into websites, mobile apps, and custom advertising platforms. The platform supports asynchronous ad loading, custom targeting attributes, dynamic ad rendering, conversion tracking, third-party integrations, and single-page application (SPA) workflows. Combined with features such as auto-refreshing, custom renderers, and dynamic ad loading, the platform can support both direct and programmatic advertising workflows.

Related articles

Tags cloud