> For the complete documentation index, see [llms.txt](https://docs.hbwrapper.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hbwrapper.com/public-api.md). # 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](/configuration.md#globalvar)). 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](/customization.md). ## 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 ```html
``` ## 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. ```javascript (pbjs = pbjs || { cmd: [] }).cmd.push(function () { pbjs.refresh(); }); ``` * **Refresh Adunits**: Refresh by GAM ad unit codes. ```javascript (pbjs = pbjs || { cmd: [] }).cmd.push(function () { pbjs.refreshAdunits(['/dfpAccountId/Adunit1','/dfpAccountId/Adunit2']); }); ``` * **Refresh IDs**: Refresh by element IDs. ```javascript (pbjs = pbjs || { cmd: [] }).cmd.push(function () { pbjs.refreshIds(['div-id-1','div-id-2']); }); ``` * **Refresh Elements**: Refresh by element handles. ```javascript (pbjs = pbjs || { cmd: [] }).cmd.push(function () { pbjs.refresh([el1, el2]); }); ``` ### Destroy * **Destroy All**: Destroy all ad units on the page. ```javascript (pbjs = pbjs || { cmd: [] }).cmd.push(function () { pbjs.destroy(); }); ``` * **Destroy Adunits**: Destroy by GAM ad unit codes. ```javascript (pbjs = pbjs || { cmd: [] }).cmd.push(function () { pbjs.destroyAdunits(['/dfpAccountId/Adunit1','/dfpAccountId/Adunit2']); }); ``` * **Destroy IDs**: Destroy by element IDs. ```javascript (pbjs = pbjs || { cmd: [] }).cmd.push(function () { pbjs.destroyIds(['div-id-1','div-id-2']); }); ``` * **Destroy Elements**: Destroy by element handles. ```javascript (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** ```javascript (pbjs = pbjs || { cmd: [] }).cmd.push(function () { pbjs.processAdsOnPage(); }); ``` * **Alternative (DOM Event)** ```javascript document.dispatchEvent(new CustomEvent('aaw', { detail: { command: 'processAdsOnPage' } })); ``` ### Privacy Settings Pass privacy signals for compliance frameworks. * **Set Privacy Settings** ```javascript (pbjs = pbjs || { cmd: [] }).cmd.push(function () { pbjs.setPrivacySettings({ childDirectedTreatment: true }); }); ``` * **Set Multiple Privacy Settings** ```javascript (pbjs = pbjs || { cmd: [] }).cmd.push(function () { pbjs.setPrivacySettings({ childDirectedTreatment: true, underAgeOfConsent: true }); }); ``` * **Clear Privacy Setting** ```javascript (pbjs = pbjs || { cmd: [] }).cmd.push(function () { pbjs.setPrivacySettings({ childDirectedTreatment: null }); }); ``` ### Wrapper Settings Configure global wrapper behavior. * **Set Timeout (ms)** ```javascript (pbjs = pbjs || { cmd: [] }).cmd.push(function () { pbjs.setWrapperConfig('timeout', 800); }); ``` * **Set Lazy Load Fetch Distance (px)** ```javascript (pbjs = pbjs || { cmd: [] }).cmd.push(function () { pbjs.setWrapperConfig('lazyLoadFetch', 1500); }); ``` * **Set Lazy Load Fetch Distance in Portviews** ```javascript (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. ```javascript 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. ```javascript (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. ```javascript (pbjs = pbjs || { cmd: [] }).cmd.push(function () { const config = pbjs.getWrapperConfig(); console.log('Wrapper config:', config); }); ``` * **getWrapperInternalAdunits()**: Returns the internal list of wrapper ad units. ```javascript (pbjs = pbjs || { cmd: [] }).cmd.push(function () { const adunits = pbjs.getWrapperInternalAdunits(); console.log('Wrapper adunits:', adunits); }); ``` * **getWrapperDeviceDetection()**: Returns detected device information used by the wrapper. ```javascript (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: ```javascript (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: ```javascript (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 --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.hbwrapper.com/public-api.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.