Overview

AdEngine is a simple to use and configure, yet powerful product. Depending on the use case and how complex the page integration is, AdEngine can be used in various ways.

Declarative Configuration, which provides simple configuration and usage
Functional Configuration, which provides power features for complex use cases

Declarative Configuration

This is the recommended way to use and configure AdEngine as it is very easy to use, robust against configuration errors, and fits many use cases.
Declarative configuration only requires a definition of a configuration object in the page head, before loading the AdEngine script.

Syntax

window.snigelPubConf = {
  "adengine": {
    "activeAdUnits": Array<String>, null or undefined,
    "activeLots":  Array<AuctionLot>, null or undefined,
    "additionalGptAdSlotIds": Array<String>,
    "staticLabels": Array<String>,
    "sensitiveContent": Boolean,
    "targeting": {
      "key1": Number,
      "pbjs": {
        "specific-bidder-parameter": "value"
      }
    }
  }
}

`snigelPubConf`

The object snigelPubConf is declared in the window context and used to describe a page specific ad-tag setup. AdEngine will read the declarations from here when running an automatic auction. When using manual auction, do not declare the object and continue reading the functional configuration section.

`adengine.activeAdUnits`

The array activeAdUnits declares the ad-units to run an initial auction on this page. Only include ad-units that are available on this page.
The presence of the activeAdUnits array will run an automatic auction for the ad-units listed in the array, even if AdEngine is configured to do manual auction.
Set to undefined if the ad-units should be auctioned in manual-auction mode only. For doing an auction of all units in auto-auction mode, set to undefined or do not declare at all.
If no auction is to be produced, heading directly to the ad server phase (e.g., to refresh some publisher GPT ad units), either set activeAdUnits array to be an empty array or null.
Find more information about ad-units, their naming, and usage in the documentation of startAuction.

`adengine.activeLots`

The array activeLots declares the auction lots to run an initial auction on this page and/or have some special configuration like lazy loading, video URLs or override settings for GPT ad unit path or auction sizes. Only include lots that are available on this page.
Having the activeLots field in the snigelPubConf object will take precedence over the activeAdUnits field. This means that if both activeAdUnits and activeLots fields are defined in the object, only the last one will be used.
AuctionLot object structure is the same as documented in the startAuction document, and can give one more freedom to define in which divs in the publisher's page will the ad units run, or set special behaviors for the units like lazy loading or specific auction sizes.
The presence of the activeLots array will run an automatic auction for the lots listed in the array, even if AdEngine is configured to do manual auction.
Set to undefined if the ad-units should be auctioned in manual-auction mode only. For doing an auction of all units in auto-auction mode, set to undefined or do not declare at all.
If no auction is to be produced, heading directly to the ad server phase (e.g., to refresh some publisher gpt ad units), either set activeLots array to be an empty array or null.
Find more information about auction lots, their naming, and usage in the documentation of startAuction.

`adengine.additionalGptAdSlotIds`

The array additionalGptAdSlotIds declares GPT ad-units using their div element id. GPT ad-units are defined using googletag.defineSlot. These additional ad-units will be passed to the Ad Manager without being processed by AdEngine. This allows running all ads through a single call to Ad Manager.

`adengine.staticLabels`

The array staticLabels is used to pass labels to AdEngine. These labels can be used for page specific scenarios and advanced options.

`adengine.sensitiveContent`

The boolean sensitiveContent is used to declare pages that contain sensitive/inappropriate text, image, audio, video, or any other type of content that violate Google Publisher Policies. In case of sensitive content on a page, declare "sensitiveContent": true, which will skip Google AdServer in the bidding process, preventing policy violations, and will render header bidding ads only.

`adengine.targeting.key1`

The number "targeting.key1" is used to associate a value to a key for all the units being served by AdEngine, which in turn allows fetching reports using those key-value pairs. The "targeting.key1" must always be an integer from 1-100. If the key is not defined, 0 will be used as default value. This allows differentiating between impressions having a dedicated value or no value assigned.

`adengine.targeting.pbjs`

The object "targeting.pbjs" is used to define the specific targeting keys for any bidder. Some Bidders/SSPs allow the use of specific parameters to improve their bidding performance. These parameters will be passed in the Prebid configuration.
These bidder-specific keys must be defined within this object this way "adengine.targeting.pbjs.specific-bidder-parameter", so that they can be passed correctly in the Prebid configuration. As demonstrated above.
These keys must have a unique name to be easily related to the Bidder/SSP. However, the same bidder can have more than one "targeting.pbjs.specific-bidder-parameter" defined.

Examples

Auction ads for 2 units

<script data-cfasync="false" type="text/javascript">
  window.snigelPubConf = {
    "adengine": {
      "activeAdUnits": ["topleaderboard", "sidebar"]
    }
  }
</script>
<script data-cfasync="false" async src="https://cdn.snigelweb.com/adengine/**site.domain**/loader.js" type="text/javascript"></script>

Auction ads for the same unit in two different placement

Since the same ad unit is being auctioned twice for different placements, it's recommended to use the same gpIdUniquifier—the original one—for both auctions. This ensures that SSPs are aware that it is indeed the same unit, allowing for better tracking and optimization.

<script data-cfasync="false" type="text/javascript">
  window.snigelPubConf = {
    "adengine": {
      "activeLots": [
        { placement: 'adngin-sidebar-0', adUnit: 'sidebar', gpIdUniquifier: 'adngin-sidebar-0' },
        { placement: 'adngin-sidebar-1', adUnit: 'sidebar', gpIdUniquifier: 'adngin-sidebar-0' }
      ]
    }
  }
</script>
<script data-cfasync="false" async src="https://cdn.snigelweb.com/adengine/**site.domain**/loader.js" type="text/javascript"></script>

Auction ads for AdEngine and GPT ad-units

<script data-cfasync="false" type="text/javascript">
  // define ad-slot using googletag defineSlot
  window.googletag = window.googletag || { cmd: [] };
  googletag.cmd.push(function() {
    googletag.defineSlot("/1234567/incontent", [160, 600], "incontent-div").
      addService(googletag.pubads());
  });
</script>
<script data-cfasync="false" type="text/javascript">
  window.snigelPubConf = {
    "adengine": {
      "activeAdUnits": ["topleaderboard", "sidebar"],
      "additionalGptAdSlotIds": ["incontent-div"]
    }
  }
</script>
<script data-cfasync="false" async src="https://cdn.snigelweb.com/adengine/**site.domain**/loader.js" type="text/javascript"></script>

Auction ads for GPT only

This example will only auction GPT ad-units. Please note that the element activeAdUnits is still mandatory and needs to be set to an empty array in that case. If the element would be missing, no automatic auction would happen in manual auction mode. In automatic auction mode all existing ad-units would be auctioned.

<script data-cfasync="false" type="text/javascript">
  // define ad-slot using googletag defineSlot
  window.googletag = window.googletag || { cmd: [] };
  googletag.cmd.push(function() {
    googletag.defineSlot("/1234567/incontent", [160, 600], "incontent-div").
      addService(googletag.pubads());
  });
</script>
<script data-cfasync="false" type="text/javascript">
  window.snigelPubConf = {
    "adengine": {
      "activeAdUnits": [],
      "additionalGptAdSlotIds": ["incontent-div"]
    }
  }
</script>
<script data-cfasync="false" async src="https://cdn.snigelweb.com/adengine/**site.domain**/loader.js" type="text/javascript"></script>

Auction ads with a bidder's specific parameter defined

<script data-cfasync="false" type="text/javascript">
  window.snigelPubConf = {
    "adengine": {
      "activeAdUnits": ["topleaderboard"],
       "targeting": {
          "pbjs": {
            "specialization": "liver"
          }
       }
    }
  }
</script>
<script data-cfasync="false" async src="https://cdn.snigelweb.com/adengine/**site.domain**/loader.js" type="text/javascript"></script>

Functional Configuration

The functional configuration is recommended when using advanced feature or complex scenarios for showing ads on the page. Examples of complex scenarios are infinite scroll or slide shows.
The functional configuration is using AdEngine functions to trigger the desired behavior.

Syntax

To configure and use AdEngine in a functional way, an event listener and a command queue is used.

window.addEventListener('adnginLoaderReady', function() {
  // when we enter here, we have access to adngin.queue, googletag.queue, 
  // pbjs.que... we can use these command queues to configure or execute
  // whatever we want, like starting an auction for example
  adngin.queue.push(function() {
    adngin.cmd.startAuction();
  });
});

Command queue

AdEngine is using the concept of a command queue to queue API commands even before the full stack is loaded. This is the same concept as being used by GPT and AdSense.
The command queue is a structure created even before AdEngine object is complete and ready to execute. This is intended to avoid having commands lost by having an incomplete object. When the adngin object is ready to execute its functions, it then processes the command queue and executes whatever commands are there, guaranteeing a logical order of execution provided by the event system (e.g., the startAuction command cannot run before the configuration commands are run).
So to execute a command in AdEngine, it should be added to the command queue, which is a Javascript array, using the notation adngin.queue.push(), as shown below:

// add a new command to AdEngine's queue
adngin.queue.push(function() {
  adngin.cmd.startAuction();
});

All available functions for AdEngine can be found in AdEngine's API reference documentation.

`adnginLoaderReady` event

The adnginLoaderReady event is dispatched at the window level of the browser after the AdEngine loader script has finished initializing all the basic variables needed to run AdEngine, like adngin.queue.
This means that at the time the event listener function is called, the callback has access to the adngin object, its queue field, and the same happening for the GPT object googletag or AdSense and their respective command queues.

window.addEventListener('adnginLoaderReady', function() {
  // In the event listener it is safe to access command queues like adngin.queue or googletag.queue
  adngin.queue.push(function() {
    adngin.cmd.startAuction();
  });
});

The adnginLoaderReady event is dispatched only once at loading time. Therefore it is important to define the listener before the loading script tag.
If AdEngine is used after page load, the event cannot be used to check AdEngine availability. In this case the boolean adngin.adnginLoaderReady must be used.

This is an example when a manual auction is used after page load time, for example after user interaction:

if(window.adngin && window.adngin.adnginLoaderReady) {
  // When adnginLoaderReady boolean is true, it is safe to access command queues like adngin.queue or googletag.queue
  adngin.queue.push(function() {
    adngin.cmd.startAuction();
  });
};

It is important to always use either the event adnginLoaderReady or the boolean adngin.adnginLoaderReady to safely call AdEngine. The two methods could be combined like shown in the following example:

function doSomething() {
  adngin.queue.push(function() {
    adngin.cmd.startAuction();
  });
}
if(window.adngin && window.adngin.adnginLoaderReady) { doSomething(); }
else { window.addEventListener('adnginLoaderReady', doSomething); }

Examples

Starting an auction for all ad units in their standard placements

Wait for AdEngine loader to be ready, then use the command queue to run an auction of all available ad tags using startAuction.

<script data-cfasync="false" type="text/javascript">
  window.addEventListener('adnginLoaderReady', function() {
    adngin.queue.push(function() {
      // trigger a new auction
      adngin.cmd.startAuction();
    });
  });
</script>
<script data-cfasync="false" async src="https://cdn.snigelweb.com/adengine/**site.domain**/loader.js" type="text/javascript"></script>

Use GPT ad-units together with AdEngine and start an auction

Wait for AdEngine loader to be ready, then use the command queue to add GPT ad-units using setGoogletagAdSlotElementIds and run an auction of all available ad tags using startAuction.

<script data-cfasync="false" type="text/javascript">
  // define ad-slot using googletag defineSlot
  window.googletag = window.googletag || { cmd: [] };
  googletag.cmd.push(function() {
    googletag.defineSlot("/1234567/incontent", [160, 600], "incontent-div").
      addService(googletag.pubads());
  });
</script>
<script data-cfasync="false" type="text/javascript">
  window.addEventListener("adnginLoaderReady", function() {
    adngin.queue.push(function() {
      adngin.cmd.setGoogletagAdSlotElementIds(["incontent-div"]);
      adngin.cmd.startAuction();
    });
  });
</script>
<script data-cfasync="false" async src="https://cdn.snigelweb.com/adengine/**site.domain**/loader.js" type="text/javascript"></script>

AdEngine Configuration and Usage

Overview

Declarative Configuration

Syntax

snigelPubConf

adengine.activeAdUnits

adengine.activeLots

adengine.additionalGptAdSlotIds

adengine.staticLabels

adengine.sensitiveContent

adengine.targeting.key1

adengine.targeting.pbjs

Examples

Auction ads for 2 units

Auction ads for the same unit in two different placement

Auction ads for AdEngine and GPT ad-units

Auction ads for GPT only

Auction ads with a bidder's specific parameter defined

Functional Configuration

Syntax

Command queue

adnginLoaderReady event

Examples

Starting an auction for all ad units in their standard placements

Use GPT ad-units together with AdEngine and start an auction

`snigelPubConf`

`adengine.activeAdUnits`

`adengine.activeLots`

`adengine.additionalGptAdSlotIds`

`adengine.staticLabels`

`adengine.sensitiveContent`

`adengine.targeting.key1`

`adengine.targeting.pbjs`

`adnginLoaderReady` event