🧩Public API

This section documents the public API exposed by the wrapper, grouped into Data Attributes, Functions, and Events.

In plain terms: the "API" is the set of things you're allowed to use from your own page — HTML attributes you add to ad containers, JavaScript commands you can call (like "refresh all ads"), and events you can listen for (like "this ad became viewable"). You don't need any of this for the wrapper to work; it's here for when you want extra control.

About pbjs in the examples: pbjs is the wrapper's global control object — the handle your code uses to talk to the wrapper. Its name is set per site by the globalVar setting in config.json (see Configuration). The examples below use pbjs because that's the default; if your site uses a different globalVar, substitute that name.

Why commands are wrapped in pbjs.cmd.push(...): the wrapper loads asynchronously, so it may not be ready the instant your code runs. Instead of calling it directly, you add your instruction to a command queue (pbjs.cmd), and the wrapper runs it as soon as it's ready. The (pbjs = pbjs || { cmd: [] }) part simply makes sure the queue exists before you push to it, even if the wrapper hasn't loaded yet.

Note for those upgrading from older docs: earlier versions referred to a $$PREBID_GLOBAL$$ build macro. As of Prebid 10 that macro no longer exists. Use your configured global variable (pbjs by default), as shown throughout this page and in Customization.

Data Attributes

Add the following data- attributes to ad unit containers. Use single quotes around attribute values, especially when passing JSON.

Required: data-aaad and data-aa-adunit.

• Aaad (data-aaad): Marks the element as an ad unit.

  • Values: 'true' to enable, 'false' to disable.

  • Required on all body ad unit elements.

• Adunit (data-aa-adunit): Full GAM ad unit code path to map the element.

  • Example: '/22181265/Test_abcd' or multi-level '/22181265/Top/Child'.

  • Use the GAM Ad unit CODE, not the UI name.

  • Required.

• Sizes (data-aa-sizes): Restrict allowed sizes for the ad unit.

  • JSON array of [width,height] pairs, e.g. '[[300,250],[300,600]]'.

• OutOfPage (data-aa-outofpage): Marks the ad unit as out-of-page.

  • Values: 'true' or 'false'.

• Device (data-aa-device): Restrict display by device types.

  • JSON array of strings, e.g. '["desktop","tablet"]'.

• Targeting (data-aa-targeting): Custom GAM targeting key-values at ad unit level.

  • JSON object, e.g. '{"category":"cars","section":"auto"}'.

• Lazy Loaded (data-aa-lazy-loaded): Enable lazy loading near viewport.

  • Values: 'true' or 'false'.

• Refresh timed (data-aa-refresh-timed): Auto-refresh rate in seconds after render.

  • Integer as string, e.g. '60'.

• Refresh viewable (data-aa-refresh-viewable): Auto-refresh rate in seconds after becoming viewable.

  • Integer as string, e.g. '60'.

• Additional non hb sizes (data-aa-additional-non-h-b-sizes): Sizes sent only to GAM (excluded from HB auctions).

  • JSON array of size pairs or string "fluid", e.g. '["fluid",[1,1]]'.

• Force GAM sizes (data-aa-force-gam-sizes): Sizes sent to GAM for this ad unit, replacing the default (banner sizes + additional non-HB sizes). When set, GAM slot is defined with exactly these sizes.

  • JSON array of size pairs or "fluid", e.g. '[[300,250],[300,600]]'.

Example

<div
  data-aaad='true'
  data-aa-adunit='/22181265/Test_abcd'
  data-aa-sizes='[[300,250],[300,600]]'
  data-aa-device='["desktop","tablet"]'
  data-aa-targeting='{"category":"cars","section":"auto"}'
  data-aa-lazy-loaded='true'
></div>

Functions

All function calls should be queued and executed via the global command queue pbjs.cmd. Replace examples accordingly.

Refresh

• Refresh All: Refresh all ad units on the page.

(pbjs = pbjs || { cmd: [] }).cmd.push(function () {
  pbjs.refresh();
});

• Refresh Adunits: Refresh by GAM ad unit codes.

(pbjs = pbjs || { cmd: [] }).cmd.push(function () {
  pbjs.refreshAdunits(['/dfpAccountId/Adunit1','/dfpAccountId/Adunit2']);
});

• Refresh IDs: Refresh by element IDs.

(pbjs = pbjs || { cmd: [] }).cmd.push(function () {
  pbjs.refreshIds(['div-id-1','div-id-2']);
});

• Refresh Elements: Refresh by element handles.

(pbjs = pbjs || { cmd: [] }).cmd.push(function () {
  pbjs.refresh([el1, el2]);
});

Destroy

• Destroy All: Destroy all ad units on the page.

(pbjs = pbjs || { cmd: [] }).cmd.push(function () {
  pbjs.destroy();
});

• Destroy Adunits: Destroy by GAM ad unit codes.

(pbjs = pbjs || { cmd: [] }).cmd.push(function () {
  pbjs.destroyAdunits(['/dfpAccountId/Adunit1','/dfpAccountId/Adunit2']);
});

• Destroy IDs: Destroy by element IDs.

(pbjs = pbjs || { cmd: [] }).cmd.push(function () {
  pbjs.destroyIds(['div-id-1','div-id-2']);
});

• Destroy Elements: Destroy by element handles.

(pbjs = pbjs || { cmd: [] }).cmd.push(function () {
  pbjs.destroy([el1, el2]);
});

Dynamic Content Processing

When new ad unit DIVs are injected after page load, notify the wrapper to process them.

• Process Ads on Page

(pbjs = pbjs || { cmd: [] }).cmd.push(function () {
  pbjs.processAdsOnPage();
});

• Alternative (DOM Event)

document.dispatchEvent(new CustomEvent('aaw', { detail: { command: 'processAdsOnPage' } }));

Privacy Settings

Pass privacy signals for compliance frameworks.

• Set Privacy Settings

(pbjs = pbjs || { cmd: [] }).cmd.push(function () {
  pbjs.setPrivacySettings({
    childDirectedTreatment: true
  });
});

• Set Multiple Privacy Settings

(pbjs = pbjs || { cmd: [] }).cmd.push(function () {
  pbjs.setPrivacySettings({
    childDirectedTreatment: true,
    underAgeOfConsent: true
  });
});

• Clear Privacy Setting

(pbjs = pbjs || { cmd: [] }).cmd.push(function () {
  pbjs.setPrivacySettings({
    childDirectedTreatment: null
  });
});

Wrapper Settings

Configure global wrapper behavior.

• Set Timeout (ms)

(pbjs = pbjs || { cmd: [] }).cmd.push(function () {
  pbjs.setWrapperConfig('timeout', 800);
});

• Set Lazy Load Fetch Distance (px)

(pbjs = pbjs || { cmd: [] }).cmd.push(function () {
  pbjs.setWrapperConfig('lazyLoadFetch', 1500);
});

• Set Lazy Load Fetch Distance in Portviews

(pbjs = pbjs || { cmd: [] }).cmd.push(function () {
  pbjs.setWrapperConfig('lazyLoadFetchPortview', 2);
});

Globals

Global variables exposed by the wrapper.

• isLoaded: Boolean that indicates when the wrapper has finished loading.

if (pbjs && pbjs.isLoaded) {
  console.log('Wrapper ready');
} else {
  (pbjs = pbjs || { cmd: [] }).cmd.push(function () {
    console.log('Wrapper is now ready');
  });
}

• wrapperVersion: String representing the wrapper version.

(pbjs = pbjs || { cmd: [] }).cmd.push(function () {
  console.log('Wrapper version:', pbjs.wrapperVersion);
});

Wrapper Introspection

Utility getters for wrapper state and configuration.

• getWrapperConfig(): Returns the current wrapper configuration object.

(pbjs = pbjs || { cmd: [] }).cmd.push(function () {
  const config = pbjs.getWrapperConfig();
  console.log('Wrapper config:', config);
});

• getWrapperInternalAdunits(): Returns the internal list of wrapper ad units.

(pbjs = pbjs || { cmd: [] }).cmd.push(function () {
  const adunits = pbjs.getWrapperInternalAdunits();
  console.log('Wrapper adunits:', adunits);
});

• getWrapperDeviceDetection(): Returns detected device information used by the wrapper.

(pbjs = pbjs || { cmd: [] }).cmd.push(function () {
  const device = pbjs.getWrapperDeviceDetection();
  console.log('Wrapper device detection:', device);
});

Events

Refer to your integration guide for any additional events available in your build.

impressionViewable

Fires once per ad render when the wrapper’s own viewability tracker considers the impression viewable: at least 50% of the slot’s bounding box intersects the viewport for a continuous 1 second. This applies to GAM-rendered slots and fallback-rendered creatives. It is independent of config.refresh.viewabilityProvider (refresh scheduling still only uses the wrapper tracker when viewabilityProvider is 'wrapper').

For GAM, observation begins only after a non-empty slotRenderEnded (no creative means no tracker on that event). If the wrapper then serves a fallback creative, observation starts from the fallback render instead.

Subscribe with pbjs.onEvent inside a command callback so the handler is registered after the wrapper registers the event name:

(pbjs = pbjs || { cmd: [] }).cmd.push(function () {
  pbjs.onEvent('impressionViewable', function (data) {
    console.log('Ad became viewable:', data);
  });
});

Payload

• divId — DOM id of the ad container element.

• adunit — GAM ad unit path (data-aa-adunit on the container).

• eventTrigger — 'gam' for GAM-rendered impressions, or a fallback reason code such as 'fallbackImps', 'fiH', 'fiFTF', 'fiECF'.

• advertiserId — For GAM: line-item advertiser id, or companyIds[0] when present (e.g. open bidding). For fallback: winning bidder code from Prebid targeting when available, otherwise 'house'.

• targetingMap — GAM slot targeting map for GAM renders, or the Prebid targetingMap passed into the fallback renderer.

• renderedAt — Epoch milliseconds when the render was recorded (observation start).

• viewableAt — Epoch milliseconds when the 1 s viewability dwell completed.

• timeToViewable — viewableAt - renderedAt in milliseconds (includes the 1 s dwell).

fallbackRenderEnded

Fires when a fallback-rendered creative finishes parsing inside its iframe (the browser has reached DOMContentLoaded for that document). GAM-rendered slots do not trigger this event. The event is not emitted when a fallback render is skipped (e.g. rich media formats or the dedup guard that prevents a double render in the same slot).

Subscribe with pbjs.onEvent inside a command callback so the handler is registered after the wrapper registers the event name:

(pbjs = pbjs || { cmd: [] }).cmd.push(function () {
  pbjs.onEvent('fallbackRenderEnded', function (data) {
    console.log('Fallback render finished parsing:', data);
  });
});

Payload

• divId — DOM id of the ad container element.

• adunit — GAM ad unit path (data-aa-adunit on the container).

• eventTrigger — Fallback reason code such as 'fallbackImps', 'fiH', 'fiFTF', 'fiECF'.

• advertiserId — Winning bidder code from Prebid targeting when available, otherwise 'house'.

• targetingMap — The Prebid targetingMap passed into the fallback renderer (may be emp