Functionality

The function adngin.cmd.startAuction() is used to start an auction to display or refresh ads present on the page.

Syntax

function adngin.cmd.startAuction(lots, callback)

Parameters

lots

value undefined

When lots is undefined, AdEngine will start an auction for all ad units in its configuration.

value null

When lots is null, AdEngine will not start an auction and immediately call the ad server to refresh GPT ad-units.

value Array<string>

This is the simplest way to select which ad units are going to be auctioned. It's a simple array holding the ad unit names that will take part in the auction. These will be auctioned for their standard placement names, which means that, e.g., adunit1 will be assumed to have a corresponding div in the page with id adngin-adunit1-0.
The placement name is derived from the ad unit name by adding the prefix adngin- and suffix -0, which will result with an example ad unit name of adunit1 to the placement name adngin-adunit1-0.
To know which ad units are available under AdEngine management, the function getAvailableAdUnitNames() can be used in the browser console to get their names.

value Array<AuctionLot>

This variant should be used when either placement do not follow the standard nomenclature as defined above, or enhanced features are required.

AuctionLot = {
  adUnit: string,
  placement: string,
  lazyLoad?: boolean,
  contentVideoUrl?: string,
  sizes?: Array<Array<integer> | string>,
  adUnitPath?: string
};

AuctionLot.adUnit and AuctionLot.placement

Defines ad unit names and their respective placement/div id on the page.

Example:

AuctionLot = {
  adUnit: "adUnit1Name",
  placement: "adUnit1DivName"
};

The function getAvailableAdUnitNames() can be used in the browser console to get the existing ad units under AdEngine.

AuctionLot.lazyLoad

AdEngine also allows to lazy load ads that are not initially visible in the publisher's page. This can lead to better page performance, by loading the ads only when they get into view, but please take into consideration that it may also impact earnings if the page rarely gets scrolled to the lazy loaded ad position.
To enable lazy loading for a particular lot, the lazyLoad field needs to be added to the AuctionLot structure as follows:

AuctionLot = {
  adUnit: "adUnit1Name",
  placement: "adUnit1DivName",
  lazyLoad: true
};

⚠️ Lazy loading of ads, given the risk it may present to earnings, is globally disabled in AdEngine by default. If you want to use it, please ask your account manager to enable it in AdEngine prior to start using it.

AuctionLot.contentVideoUrl

It is possible to pass a specific content video URL to units that provide instream video ads. The publisher content video in these cases should be passed through the contentVideoUrl parameter in the AuctionLot structure as follows:

AuctionLot = {
  adUnit: "adUnit1Name",
  placement: "adUnit1DivName",
  contentVideoUrl: "<url to publisher content video>"
};

AuctionLot.sizes

AdEngine can be instructed to only show a subset of sizes on a specific lot. This allows to re-use an ad unit on a placement with size limitations, only supporting specific sizes.

Example:

AuctionLot = {
  adUnit: "adUnit1Name",
  placement: "adUnit1DivName",
  sizes: [[300, 250], [300, 600], "fluid"]
};

⚠️ Please take into consideration that the provided array of sizes should be a subset of the originally-defined sizes in the adunit setup. Providing wrong or non-existent sizes may lead to unfilled impressions and therefore loss of earnings.

AuctionLot.adUnitPath

Overriding the ad unit path (Google Ad Manager path) supports using AdEngine ad units with multiple GAM paths. This method is only used for specific setups, like using a GAM slot per page instead of per placement type, and to overcome those difficulties.

Example:

AuctionLot = {
  adUnit: "adUnit1Name",
  placement: "adUnit1DivName",
  adUnitPath: "myGAMAdUnitPathName"
};

⚠️ GAM path overrides of ads, given the risk it may present to earnings, is globally disabled in AdEngine by default. To allow GAM adunit path override, the adunit setup needs to be updated to enable this feature. Please contact your Snigel Account Manager to enable this feature for you if you need it.

callback

The callback function that is called with the function call result.

Syntax:
function callback(result:CallbackResult, success:boolean)

result

This is a JSON object holding the function call result, which is passed to the provided callback function in order to execute some specific action upon the function call. The object structure is as follows:

CallbackResult = {
  message: "<string holding a debug log of the function call result>"
}

success

A boolean representing the function call success status, true for success, false for failure.

Description

A call to startAuction() will start a new auction for the ad-units passed as parameter. After the auction is finished it will call the ad server in order to refresh the ad unit placements with the new ads. In this phase GPT external ad-units set with setGoogletagAdSlotElementIds or setGoogletagAdSlots are refreshed together with AdEngine ad-units.
If there is an existing auction running, AdEngine queues the new auction until the last one is finished. Subsequent calls to startAuction() will refresh ads, which should be used carefully as wrong refresh intervals can cause Google policy violations.

If startAuction() is called without any parameters or with the first parameter set to undefined, AdEngine will start an auction for all ad units in its configuration. After the auction is finished it will call the ad server, including external GPT ad-units, in order to refresh the ad unit placements with the new ads.

If the first parameter is either null or an empty array, no auction is started. Just the ad server will be called, including external GPT ad-units, in order to refresh the ad unit placements with the new ads.

If the parameter is a valid array of ad-unit names or lots as described above, the auction will be started for those units. After the auction is finished it will call the ad server, including external GPT ad-units, in order to refresh the ad unit placements with the new ads.

Automatic Auction Mode

AdEngine is running in automatic auction mode by default. Automatic auction means that as soon as AdEngine is loaded in the page, it will start the auction and display ads. It will take into account the active ad-units defined in snigelPubConf or otherwise auction all available ad-units.
In automatic auction mode, startAuction() is used to refresh ad-units, typically triggered by the page on user interaction.

Manual Auction Mode

Manual auction means that AdEngine is loaded in the page and not displaying ads by default. The only exception is when active ad-units are defined using declarative configuration, in that case AdEngine will do an automatic auction of these ad-units.
If no declarative configuration is found, it is the page responsibility to call startAuction() to display or refresh ads. Manual auction mode gives more freedom, in a programmatic way, how and when ads are displayed. Manual auction mode is typically used in advanced scenarios to have full control of displaying ads.

⚠️ Please note that failing to call startAuction() in manual auction mode will result in no ads being shown.

Scope

The function can be called after AdEngine loader is ready and the AdEngine queue is defined, see functional configuration for more details.

Examples

All the examples below assume that there is a total of three ad units whose names are "adUnit1", "adUnit2" and "adUnit3", and five possible placements for them ("adngin-adUnit1-0", "adngin-adUnit2-0", "adngin-adUnit3-0", "otherdiv1" and "otherdiv2").

Starting an auction for all ad units in their standard placements

window.addEventListener('adnginLoaderReady', function() {
  adngin.queue.push(function() {
    // trigger a new auction
    adngin.cmd.startAuction();
  });
});

This will start an auction for ad units "adUnit1", "adUnit2" and "adUnit3" in their respective placements "adngin-adUnit1-0", "adngin-adUnit2-0" and "adngin-adUnit3-0".

Starting an auction for "adUnit1" and "adUnit3" in their standard placements

window.addEventListener('adnginLoaderReady', function() {
  adngin.queue.push(function() {
    // trigger a new auction
    adngin.cmd.startAuction(["adUnit1", "adUnit3"]);
  });
});

This will start an auction for ad units "adUnit1" and "adUnit3" in placements "adngin-adUnit1-0" and "adngin-adUnit3-0".

Starting an auction for "adUnit1" and "adUnit2" in placements "otherdiv1" and "otherdiv2"

window.addEventListener('adnginLoaderReady', function() {
  adngin.queue.push(function() {
    // trigger a new auction
    adngin.cmd.startAuction([
      {
        adUnit: "adUnit1",
        placement: "otherdiv1"
      },
      {
        adUnit: "adUnit2",
        placement: "otherdiv2"
      }
    ]);
  });
});

Using GAM path per page with custom sizes

This example uses adUnit1 several times on the same page, using custom size overrides per placement and page specific GAM paths overriding the default path set up by the account manager.

window.addEventListener('adnginLoaderReady', function() {
  adngin.queue.push(function() {
    // trigger a new auction
    adngin.cmd.startAuction([
      {
        adUnit: "adUnit1",
        placement: "otherdiv1",
        sizes: [[300, 250]],
        adUnitPath: "pageGAMAdUnitPathName"
      },
      {
        adUnit: "adUnit1",
        placement: "otherdiv2",
        sizes: [[300, 600]],
        adUnitPath: "pageGAMAdUnitPathName"
      }
    ]);
  });
});