Integration

Basic setup

To get started with Htag, you need to add the Htag script to the of your HTML document. This script will load the Htag and initialize it with your configuration. First, you need to go to Adconsole.com, create a tag, retrieve it’s unique ID.

The basic integration would look like this:

<script defer="defer" async="async" src="https://adnz.co/header.js?id=ID"></script>

You can also add the script to your page using Javascript:

var script = document.createElement('script');
script.src = 'https://adnz.co/header.js?id=ID';
script.async = true;
script.defer = true;
document.head.appendChild(script);

CSP setup

If you are using Content Security Policy (CSP), you need to pass nonce to the script tag. You can do this by adding a nonce attribute to the script tag. The nonce value should be generated by you on the server side and then passed to the client side on setup step.

var nonce = 'your-nonce-value'; // Generate this on the server side
var script = document.createElement('script');
script.src = 'https://adnz.co/header.js?id=ID';
script.async = true;
script.defer = true;
script.setAttribute('nonce', nonce);
document.head.appendChild(script);

Unfortunately, not all third-party scripts we integrate with support CSP and nonce, but we will try our best passing the nonce to them. The other option would be to whitelist all domains used by header tag, but there are hundreds of different third-party bidders with their own set of domains — that won’t be easy.

Single page applications

If you are using a single page application (SPA) framework like React, Vue, or Angular, you need to make sure that the Htag script is loaded only once and is not reloaded on every page change. It won’t break anything if you load it multiple times, but it won’t be very performant.

Also make sure to call the Refresh Ads api method on every page change to refresh the ads. We can’t reliably detect when the page changes in SPAs, so you need to call this method manually immidiately after page transition.

Command Queue

You can use built-in command que to queue commands to be executed after the Htag script is loaded. This is useful if you want to setup all the integration code before the script is loaded.

window.htag = window.htag || {};
window.htag.que = window.htag.que || [];
window.htag.que.push(() => {
  // Your code here
});

Standalone Integration

For advanced users who prefer manual configuration without using Adconsole.com, HTAG supports standalone integration. This approach allows you to configure placements directly in your code without retrieving configuration from external APIs.

How It Works

Standalone integration bypasses the Adconsole.com configuration system and lets you:

• Define placements manually in JavaScript
• Configure all bidding parameters directly in code
• Maintain complete control over your ad configuration
• Test and develop without external dependencies

Basic Implementation

// Initialize htag command queue before the script loads
window.htag = window.htag || { que: [] };

// Queue configuration commands
window.htag.que.push(function () {
  // Define a placement with manual configuration
  window.htag.api('1').definePlacement({
    elementId: 'ad1',
    mediaTypes: ['BANNER'],
    sizes: [[970, 250]],
    adUnitPath: '/123456/example.com/page',
    skipGoogle: false,
    preloadGroup: '',
    lazyloading: true,
    minWidth: 800,
    bids: [
      {
        bidderAlias: 'xandr',
        bidder: 'xandr',
        isServer: false,
        params: {
          placementId: 12345678,
          keywords: { itests: ['true'] },
        },
      },
    ],
  });

  // Start the htag system
  window.htag.api('1').start();
});

<!-- Load htag script -->
<script defer async src="https://cdn.adnz.co/htag/htag.js"></script>

Live Example

You can view a working standalone integration example at: https://cdn.adnz.co/scripts/htag-standalone/index.htm?apn_test=TRUE

The example includes the apn_test=TRUE parameter for testing mode, which disables antifraud protection and impression counting (see Debugging for more details).

Semi-Automatic Integration

For advanced users who need more control over placement configuration, Htag supports a callback-based approach through the definePlacements method. This is particularly useful when working with server-managed configurations that include placement-specific settings.

You can also combine server-managed placements with manual definePlacement calls for additional custom placements.

Custom Placement Workflows

For advanced use cases, you can reassign the definePlacements callback to implement custom placement logic:

// Custom definePlacements implementation
window.htag.definePlacements = function (configs, settings) {
  configs.forEach((config) => {
    const customConfig = {
      ...config,
      // Apply custom transformations
      sizes: filterCustomSizes(config.sizes),
      keywords: [...(config.keywords || []), { key: 'custom', values: ['true'] }],
    };
    window.htag.api('1').definePlacement(customConfig);
  });
};