...

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.

...

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.

...

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

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

...

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

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

AuctionLot.gpIdUniquifier

The gpIdUniquifier allows you to pass a specific string to help SSPs better identify ad units when multiple instances of the same unit are called on the same page. It should always match the div ID of the first instance of the unit, which is typically the default ID generated by the AdEngine-app.

AuctionLot = {
  adUnit: "adUnit1Name",
  placement: "adUnit1DivName",
  gpIdUniquifier: "adUnit1DivName of the first instance of the adUnit"
};

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
};COPY

⚠️ 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 = {
  adUnit: "adUnit1Name",
  placement: "adUnit1DivName",
  contentVideoUrl: "<url to publisher content video>"
};COPY

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.

...

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

⚠️ 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.

...

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

success

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

...

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.

...

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 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.

...

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

Examples

...

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

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".

...

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

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

...

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

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

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

Using GAM path per page with custom sizes

...

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

...