AdEngine Configuration and Usage
- Nelson Pina
- Tiago Gaspar
- 1 Overview
- 2 Declarative Configuration
- 2.1 Syntax
- 2.1.1 snigelPubConf
- 2.1.2 adengine.activeAdUnits
- 2.1.3 adengine.activeLots
- 2.1.4 adengine.additionalGptAdSlotIds
- 2.1.5 adengine.staticLabels
- 2.1.6 adengine.sensitiveContent
- 2.1.7 adengine.targeting.key1
- 2.1.8 adengine.targeting.pbjs
- 2.2 Examples
- 2.1 Syntax
- 3 Functional Configuration
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 if we have a article scrolling page. 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>gpIdUniquifier is recommended only on article scrolling page, pages that have an article that when we get to the bottom of it a new article is added with the same ads, this will ensure the ads of the new article will be properly identified by the SSPs. If that’s the case for your page it’s recommended to request help to your account manager.
Auction ads for AdEngine and GPT ad-units
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.
Auction ads with a bidder's specific parameter defined
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.
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:
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.
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:
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:
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.
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.