> For the complete documentation index, see [llms.txt](https://docs.relevant-digital.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.relevant-digital.com/technical/integration/javascript-api/relevantdigital.loadprebid.md). # relevantDigital.loadPrebid() This function works by checking all available ***ad slots*** on the page, match them to the right placement set up in Relevant Yield and then run a Prebid auction for these placements followed by an ad requests. "Ad slots" are different data-structures depending on the ad server used: {% columns %} {% column %} **Google Ad Manager** Use a [googletag.Slot](https://developers.google.com/publisher-tag/reference#googletag.slot) created with [googletag.defineSlot()](https://developers.google.com/publisher-tag/reference#googletag.defineSlot). {% endcolumn %} {% column %} **Xandr** Use a tag object created with [apntag.defineTag()](https://docs.xandr.com/bundle/seller-tag/page/seller-tag/define-tag.html). {% endcolumn %} {% endcolumns %} {% hint style="info" %} When **slot** appears in this documentation or API objects, it refers to the ad-server-created object only for Google Ad Manager without **delayedAdserverLoading**. For other ad servers, it refers to a Relevant Yield object with a minimal, similar API. {% endhint %} Ad slots can be created in two ways, either: * Using the normal ad server functionality (**googletag.defineSlot()** etc). * By adding **\
** elements with the **data-ad-unit-id** attribute where the value is the id/path of the placement in the ad server. To make this work you need to set the **manageAdserver** parameter in the call to **loadPrebid()**. One advantage of this method is that the same dimensions/sizes that is specified in Yield will be used when our code defines the slots. Example: ```
``` ```
``` ### Amazon UAM/TAM Relevant Yield also supports Amazon. In case any of the loaded placements are configured to use Amazon, then a separate call to Amazon will be done in parallel with the Prebid auction. In this document a "Prebid auction" refers to all headerbidding auctions, including Prebid and/or Amazon. ### When to call `loadPrebid()` This function can be called any number of times on the same page-view and the behavior (which placements that will be loaded) depends on the **noSlotReload** and **allowedDivIds** parameters. * For lazy-loading and infinite scroll scenarios use **noSlotReload: true** in order to only load new slots that has been created since the previous call to **loadPrebid()**. * To reload slots that has already been loaded with **loadPrebid()** - use **noSlotReload: false** (default) * To filter out which slots to load, use the **allowedDivIds** parameter. **WARNING:** Make sure to not call **loadPrebid()** multiple times unnecessarily for placements that becomes visible at the same time - in particular on page load. This will "queue" the Prebid auctions after each other which will cause unnecessary delays.\ Let's for example say that a Prebid auction takes 0.5 seconds there are 2 slots visible immediately when entering the page. If you first call **loadPrebid()** when only the first slot is available and then again when the second one is available - then the ad-request for the second slot will be done after 0.5+0.5=1 seconds instead of just 0.5 seconds.\ The alternative would be to first create the slots (manually or automatically by **data-ad-unit-id**), and *then* do a single call to **loadPrebid()**. ### Placements without header bidding In case some of your placements are not using Prebid (for example a top banner where you don't want to wait for Prebid) - then this can be solved using any of the following methods: The *preferred option* is to use the **runHbLessNow: true** parameter. This ensures that slots without headerbidding are requested immediately, without waiting for the auction. See documentation for that parameter below.\ \ The *other option* is to to manually split the **relevanDigital.loadPrebid()** calls into two different calls, where the first is only for non-headerbid placements. Example: ``` // First, load non-Prebid placements relevantDigital.loadPrebid({ ..., allowedDivIds: ['top-banner', 'interstitial'] }); // Then load the rest, use 'noSlotReload' to avoid reloading the 2 placements again. relevantDigital.loadPrebid({ ..., noSlotReload: true); ``` ### Access placement tag field data If you've created [placement tag fields](/technical/custom-configuration/configure-placement-tag-fields.md) in order to edit custom data fields per placement in Yield, then this data is accessible via **AdUnit.data -** where **AdUnit** is the representation of a placement in Relevant Yield. One way to access this data is by using the **onSlotAndUnit** callback. Example (using an imaginary placement tag field named "makeTransparent"): ``` relevantDigital.loadPrebid({    ...  onSlotAndUnit: ({ slot, unit }) => {    if(unit.data.makeTransparent) { document.getElementById(slot.getSlotElementId()).style.opacity = 0.2; }  }, }; ``` ### Add global callbacks To add global callbacks, instead of supplying them to **loadPrebid()** - please use [relevantDigital.addAuctionCallbacks()](/technical/integration/javascript-api/relevantdigital.addauctioncallbacks.md). ### Google Ad Manager example ```
``` ### Get the script URL and `configId` The URL to the script along with the mandatory **configId** parameter is available in Yield via the **Prebid configuration**s menu for the site. script2 ### Parameter reference #### Core configuration **`configId`** The **configId** string of the *Prebid Configuration* created in Yield. To list available prebid configurations you can use the **relevantDigital.getConfigs()** function. This parameter is mandatory. **`manageAdserver`** If **true** then new ad-slots will be constructed for every **\
** with **data-ad-unit-id** set to the id/path of an ad placement. In addition, "setup" of the ad server will occur: * For **Google Ad Manager** - [googeltag.pubads().disableInitialLoad()](https://developers.google.com/publisher-tag/reference#googletag.PubAdsService_disableInitialLoad) and other necessary calls will be done. * For **Xandr** ad server - [apntag.setPageOpts()](https://docs.xandr.com/bundle/seller-tag/page/seller-tag/set-page-options.html) will be called with the member id configured in the ad server settings in Yield. **`noSlotReload`** If **true**, then slots that have already been loaded won't be reloaded. This parameter should be set in lazy-load and infinite-scroll scenarios. In fact it might be used in all cases except when you explicitly want ads to reload. **`allowedDivIds`** An **array** of div-ids for ad slots that should be loaded. Notice that this will act as a *filter* for which ad slots on the page that should be loaded. \*Note: This does not apply to the div attribute "data-ad-unit-id" or any other div attribute bar the id. Example usage: ``` relevantDigital.loadPrebid({ ..., allowedDivIds: ['top-banner', 'interstitial'] }); ``` **`allowedPlacementType`** A string - *"instream"* or *"banner"*. Used for loading *only* instream placements or *only* non-instream (normal) placements. This can for example be used if you don't want to combine instream placements with the rest of the placements in the prebid auction. If you want to create a different auction for instream placements that will run after the normal auction you can use this pattern: ``` relevantDigital.loadPrebid({ ..., allowedPlacementType: 'banner' }); relevantDigital.loadPrebid({ ..., allowedPlacementType: 'instream' }); ``` **`noGpt`** It is *recommended* to always set this to **true**. For legacy reasons our script will load Google's tag script **gpt.js** if you're using **Google Ad Manager** and this parameter is *not* true. However, for performance reasons it's usually better to load this script directly in *\* on the page instead. **`delayedAdserverLoading`** For **Google Ad Manager** - a *boolean* that, when set to **true**, makes it possible to run the Prebid auction *before* loading of the GAM script (gpt.js) is completed. When using this setting the **slot** objects in callbacks etc will *not* be a **googletag.Slot** instance. Instead it will be an own type. In order to access the actual **googletag.Slot** object one must wait for it to become available via the **slot.waitGamSlot()** function. Example: ``` relevantDigital.loadPrebid({    ... delayedAdserverLoading: true,  onSlotAndUnit: ({ slot, unit }) => { slot.waitGamSlot((gamSlot) => { gamSlot.setTargeting("some", "targeting"); });  }, }; ``` **`runHbLessNow`** When set to **true**, this parameter ensures that placements without headerbidding will be requested immediately - without waiting for the Prebid/Amazon auction to end.\ **NOTICE:** This parameter will cause **onBeforeAdRequest** to be called twice per request to **relevantDigital.loadPrebid**. This is normally not a problem. But if you're using custom logic that depends on that one loadPrebid call will only cause a single ad-request - then please review this custom logic before enabling this parameter. #### Ad slot behavior **`collapseEmptyDivs`** When using **Google Ad Manager** and **manageAdServer: true** - setting this to **true** corresponds to setting the first parameter to **true** in the call to [googletag.Slot.setCollapseEmptyDiv](https://developers.google.com/publisher-tag/reference#googletag.Slot_setCollapseEmptyDiv). This can also be done individually per placement by using the **data-collapse-empty-divs** attribute, example: 
<div data-ad-unit-id="/12345/news/top_banner" data-collapse-empty-divs></div>
**`collapseBeforeAdFetch`** When using **collapseEmptyDivs** (see above) setting this parameter to true corresponds to setting the *second* parameter to **true** in the call to [googletag.Slot.setCollapseEmptyDiv](https://developers.google.com/publisher-tag/reference#googletag.Slot_setCollapseEmptyDiv). This can also be done individually per placement by using the **data-collapse-before-ad-fetch** attribute when combined with **data-collapse-empty-divs**, example: 
<div
    data-ad-unit-id="/12345/news/top_banner"
    data-collapse-empty-divs
    data-collapse-before-ad-fetch
></div>
**`noAdsInitRequestAll`** For **Google Ad Manager** the first ad request will *by default* be done by a call to **googletag.pubads.refresh()** *without* any array of slots in order to request *all* existing ad slots - not only the ones in the first auction. Set this parameter to **true** to *only* include slots that are part of the first auction in the first ad request (this is always the case for subsequent auctions anyway). **`loadUnknownSlots`** For **Google Ad Manger** and **Xandr Ad server**. Normally only slots included in the current prebid configuration is loaded - except for the first auction with Google when *not* using the **noAdsInitRequestAll** flag above. Setting this parameter to **true** will cause "unknown" ad slots to be loaded as well. Notice that the **noSlotReload** and **allowedDivIds** parameters will work as normal for these unknown slots. **`hasSharedAdUnits`** Set to **true** only if there are *multiple* placements in the same *Prebid configuration* that is sharing the *same* ad unit path in the placement ad server settings in Yield. This is a *special case* that also requires usage of an **onSlotAndUnit** callback function that returns **false** for some placements, as otherwise all slots will always be matched to the first placement in Yield. **WARNING:** This is ***absolutely not*** the recommended way to handle shared ad unit paths in **Google Ad Manger**, instead when sharing ad unit paths it's recommended to to use **Custom targeting key appended to ad unit path** and **ID of custom targeting key to append ad unit path** settings in the global ad server settings in Yield. Please contact Relevant support for more details. #### Custom ad-unit matching **`createAdUnitCode`** Callback **function** for customizing the ad unit codes in Prebid.js. Notice that this code might change anyway as we're never re-using the same ad unit code. Example: ``` relevantDigital.loadPrebid({    ...    createAdUnitCode: ({ code, unit, slot }) => { if(slot.getSlotElementId() === 'top-banner') { return 'my-top-banner-ad-unit-code'; } return null; // use the normal generated ad unit code    }, }; ``` **`divAttribute`** A string denoting the html attribute to use instead of the default "data-ad-unit-id" when specifying ad unit path/ids with **manageAdserver: true**. **`divToAdUnit`** Callback function for implementing a custom way to match a **\
** element to a placement in Yield when using **manageAdserver**. The callback will receive an array **adUnits** of all available Yield placements in the *Prebid configuration* to select from. Example: ``` relevantDigital.loadPrebid({    ...    divToAdUnit: ({ div, path, adUnits, auction, defaultFn }) => { const example = div.getAttribute('data-example'); const unit = adUnits.find((unit) => unit.data.exampleField === example) if (unit) { return unit; } return defaultFn(); // use the normal procedure    }, }; ``` ### Auction lifecycle callbacks #### `onBeforeAuctionSetup` Callback **function** that will be invoked before starting an auction. Example: ``` relevantDigital.loadPrebid({ ... onBeforeAuctionSetup: ({ auction }) => { console.info('Relevant Yield auction object', auction); }, }; ``` The callback will be called when all previous auctions are done (ad requests initiated) - but before the the check for available ad-slots. Therefore you can safely create ad-slots at this point that will be included in the auction (manually or by setting **data-ad-unit-id** on div-elements when using **manageAdserver**). #### `onSlotAndUnit` Callback **function** that will be invoked for every ad slot that will participate in the auction. *Unless* the callback function returns **false** (exactly) - as then the ad slot will be skipped. Example: ``` relevantDigital.loadPrebid({    ...    onSlotAndUnit: ({ slot, unit, requestAuction }) => {        console.info('Ad Slot', slot); console.info('Prebid.JS ad unit', unit.pbAdUnit);       console.info('Relevant Yield placement', unit); console.info('Relevant Yield auction object', requestAuction);    }, }; ``` One use-case of this callback is to do custom adjustments to the Prebid.js bid parameters, available in **unit.pbAdUnit.bids\[]**. Notice that **unit** represents one placement added in Relevant Yield. If you load the same placement multiple times in the same **loadPrebid()** call - then multiple callbacks with the same **unit** will occur. **Special case:** *use multiple Yield placements for the same slot*. This is possible by *returning* **{reUseSlot: true}**. However, this requires us to, for each slot - remove all except one ad unit instance before making the ad request. Example: ``` relevantDigital.loadPrebid({ onSlotAndUnit: ({ slot, unit }) => { return { reUseSlot: true }; }, onBeforeAdRequest: ({ auction }) => { const bySlot = new Map(); auction.usedUnitDatas.forEach((unitData) => { bySlot[unitData.slot] = bySlot[unitData.slot] || [];         bySlot[unitData.slot].push(unitData); }); // Call .remove() on all ad unit instances except the one, per slot, // that has the highest CPM bid. const cpmOf = (unitData) => unitData.getHighestBid()?.cpm || 0;      Object.values(bySlot).forEach((arr) => { arr.sort((a, b) => ( cpmOf(a) === cpmOf(b) ? 0 : (cpmOf(a) < cpmOf(b) ? -1 : 1) )); arr.slice(1).forEach((unitData) => unitData.remove()); }); }, }) ``` #### `onAuctionInitDone` Callback **function** invoked after all placements has been set up and before the Prebid.JS auction (called after **onSlotAndUnit**). Example: ``` relevantDigital.loadPrebid({    ...  onAuctionInitDone: ({ auction }) => {       console.info('Relevant Yield auction object', auction); auction.usedUnitDatas.forEach((unitData) => { const { pbAdUnit, adUnit, slot, code } = unitData;       console.info('Ad Slot', slot); console.info('Prebid.JS ad unit', pbAdUnit); console.info('Prebid.JS ad unit code', code);     console.info('Relevant Yield placement', adUnit); });  }, }; ``` #### `onBeforeAdRequest` Callback function invoked after the Prebid auction is done and immediately *before* the ad request is *initiated*. Example: ``` relevantDigital.loadPrebid({ ... onBeforeAdRequest: ({ auction }) => { console.info('Relevant Yield auction object', auction); }, }; ``` #### `onAuctionDone` Callback function invoked after the Prebid auction is done and immediately *after* the ad request has been *initiated*. Example: ``` relevantDigital.loadPrebid({ ... onAuctionDone: ({ auction }) => { console.info('Relevant Yield auction object', auction); }, }; ``` #### `onAmazonSlot` Callback **function** invoked for every Amazon slot - when using Amazon UAM/TAM in parallel with Prebid. This callback can be used for "finalizing" this slot before the call to Amazon is done. Example: ``` relevantDigital.loadPrebid({    ... onAmazonSlot: (amazonSlot, unitData) => { console.info('Ad slot, placement in Yield, etc', unitData); amazonSlot.slotParams.SOME_KEY = "SOME_VALUE" }, }; ``` #### `onAdUnitMatchingFailed` Callback when a **\
** element is referring to a path that can't be found in the prebid configuration. Example: ``` relevantDigital.loadPrebid({    ... onAdUnitMatchingFailed: ({ div, auction, path, defaultFn }) => { if (!isAnExpectedFailure(path)) { // Some kind of logic.. defaultFn(); // Default behavior (show console error) } }, }; ``` ### API call interceptors #### `pbjsCalls` This object can be used to setup functions that will *intercept* the calls done by Relevant Yield to the **pbjs.??** functions. Currently these functions are used: * **requestBids** * **addAdUnits** * **removeAdUnit** * **renderAd** * **setConfig** * **aliasBidder** * **onEvent** * **getBidResponsesForAdUnitCode** * **getHighestCpmBids** * **setTargetingForGPTAsync** * **setTargetingForAst** The callback functions will get the Relevant Yield auction objects in **this.auction**. Example: ``` relevantDigital.loadPrebid({    ... pbjsCalls: {   requestBids: function(requestObj) {         console.info('Relevant Yield auction object', this.auction);               return pbjs.requestBids(requestObj); // Do the actual call   }, }, }; ``` #### `googletagCalls` For usage with Google Ad Manager only. This object can be used to setup functions that will *intercept* the calls done by Relevant Yield to the **googletag.??** *and* **googletag.pubads().??** functions. Currently these functions are used: * **addEventListener** * **removeEventListener** * **getSlots** * **defineSlot** * **disableInitialLoad** * **enableSingleRequest** * **enableServices** * **refresh** The callback functions will get the Relevant Yield auction objects in **this.auction**. Example: ``` relevantDigital.loadPrebid({    ...   googletagCalls: {     defineSlot: function(adUnitPath, size, div) {       console.info('Relevant Yield auction object', this.auction);               return googletag.defineSlot(adUnitPath, size, div); // Do the actual call     }, }, }; ``` #### `apntagCalls` For usage with **Xandr** ad server only. This object can be used to setup functions that will *intercept* the calls done by Relevant Yield to the **apntag.??** functions. Currently the functions used are these: * **defineTag** * **loadTags** * **showTag** * **refresh** * **setKeywords** * **getTag** * **modifyTag** The callback functions will get the Relevant Yield auction objects in **this.auction**. Example: ``` relevantDigital.loadPrebid({    ...     apntagCalls: {       defineTag: function(tagData) {            console.info('Relevant Yield auction object', this.auction);           tagData.enableSafeFrame = true; // Modify something           return apntag.defineTag(tagData); // Do the actual call         },   }, }; ``` ### Bid caching and custom ad-unit codes #### Bid caching Relevant yield supports Prebid Bid Caching by enabling it under the Prebid Parameters -> Generic Prebid Config Data settings.\ For more information about bid caching, see #### Custom ad-unit code If there is a need to customise the ad unit code, define the `createAdUnitCode` and add it to the `loadPrebid` call. **Example** ``` window.relevantDigital = window.relevantDigital || {}; relevantDigital.cmd = relevantDigital.cmd || []; relevantDigital.cmd.push(function() { ... relevantDigital.loadPrebid({ createAdUnitCode({params}) => 'myCustomAdUnitCode', ... }); // Will make all adUnitCodes become myCustomAdUnitCode }) ``` `createAdUnitCode` params exposes the current `code`, the `unit` and the `slot`, useful if you need to customise based on the units metadata: **Example** `createAdUnitCode({ code, unit, slot }) => slot.getSlotElementId()` Would force the ad unit code to become the element id of the defined ad slot. ### Other ad server-specific parameters There are some other ad server specific parameters for less common ad servers as well * **Adform** * **Equativ (Smart)** * **Adnuntius** * **In-memory Adserver** ("ad server-less") {% hint style="info" %} Please send a request to Relevant support in case you need these parameters documented. {% endhint %} --- # 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.relevant-digital.com/technical/integration/javascript-api/relevantdigital.loadprebid.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.