🧩Public API

This section documents the public API exposed by the wrapper, grouped into Data Attributes, Functions, and Events. Code snippets use the global $$PREBID_GLOBAL$$ command queue interface where applicable.

Note: $$PREBID_GLOBAL$$ is a macro placeholder for the wrapper's global object. In custom scripts within this documentation, use the macro as shown. In public environments, use the actual global variable name assigned by your integration/build.

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

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 $$PREBID_GLOBAL$$.cmd. Replace examples accordingly.

Refresh

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

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

• Refresh Adunits: Refresh by GAM ad unit codes.

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

• Refresh IDs: Refresh by element IDs.

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

• Refresh Elements: Refresh by element handles.

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

Destroy

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

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

• Destroy Adunits: Destroy by GAM ad unit codes.

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

• Destroy IDs: Destroy by element IDs.

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

• Destroy Elements: Destroy by element handles.

($$PREBID_GLOBAL$$ = $$PREBID_GLOBAL$$ || { cmd: [] }).cmd.push(function () {
  $$PREBID_GLOBAL$$.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

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

• Alternative (DOM Event)

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

Privacy Settings

Pass privacy signals for compliance frameworks.

• Set Privacy Settings

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

• Set Multiple Privacy Settings

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

• Clear Privacy Setting

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

Wrapper Settings

Configure global wrapper behavior.

• Set Timeout (ms)

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

• Set Lazy Load Fetch Distance (px)

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

• Set Lazy Load Fetch Distance in Portviews

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

User Info

Retrieve information about the current user. Availability is asynchronous; calling too early may return isSet: false.

• Get User Info

// Returns an object like:
// { isSet: true, ip: '62.23x.1x3.1x5', ua: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) ... Chrome/12x.0.0.0 Safari/537.36', cc: 'R*' }
($$PREBID_GLOBAL$$ = $$PREBID_GLOBAL$$ || { cmd: [] }).cmd.push(function () {
  const info = $$PREBID_GLOBAL$$.getUserInfo();
  console.log(info);
});

Timing note: if isSet is false, listen for the updateUserInfo event to know when the data becomes available.

Globals

Global variables exposed by the wrapper.

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

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

• wrapperVersion: String representing the wrapper version.

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

Wrapper Introspection

Utility getters for wrapper state and configuration.

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

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

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

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

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

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

Events

updateUserInfo

Fired when user info becomes available or is updated. Subscribe using the standard Prebid event interface. The event payload matches the getUserInfo() return shape.

Reference: Prebid onEvent

($$PREBID_GLOBAL$$ = $$PREBID_GLOBAL$$ || { cmd: [] }).cmd.push(function () {
  $$PREBID_GLOBAL$$.onEvent('updateUserInfo', function (data) {
    // data: { isSet: true, ip: '62.23x.1x3.1x5', ua: 'Mozilla/5.0 ...', cc: 'R*' }
    console.log('User info updated', data);
  });
});

Example: Mitigate timing with getUserInfo + updateUserInfo

/* Execute function after you know the country has been detected */
($$PREBID_GLOBAL$$ = $$PREBID_GLOBAL$$ || { que: [], cmd: [] }).que.push(function () {
  // Get user info
  let userInfo = $$PREBID_GLOBAL$$.getUserInfo();

  if (!userInfo || !userInfo.isSet) {
    // If not set, listen to the updateUserInfo event
    $$PREBID_GLOBAL$$.onEvent('updateUserInfo', function (e) {
      executeFunction(e.cc);
    });
  } else {
    // If already set, execute function
    executeFunction(userInfo.cc);
  }
});

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