Publisher Optimization Prebid JS RTD Module Implementation Guide

The Publisher Optimization Prebid JS RTD Module enables you to use the Publisher Optimization while leveraging Prebid JS.

Implementing Publisher Optimization through Prebid JS is more efficient from a size and time response perspective than going through the legacy Publisher Optimization implementation, because the Prebid JS file can be hosted on the same servers as the website. The only downside is since the JavaScript is stored locally, IAS can't update the code remotely. Therefore, publishers must upgrade to get IAS's updates.

This documentation covers Prebid JS versions 5 and greater. See the Changelog below for more information.

Optimization Overview

IAS's optimization allows your ad server to automatically deliver campaigns to goals defined by IAS measurement data. This solution enables you to:

  • Sell direct campaigns to advertisers with guarantees based upon IAS data – for example, a Run of Network (RON) campaign that has 70% viewability, no brand safety risk, and no invalid traffic.

  • Set up private marketplaces (PMP) with similar guarantees under conditions (AdExchange on DFP or Data Marketplace by Xandr) – for example, a PMP containing semi-transparent inventory that has 80% viewability, no brand safety risk, and no invalid traffic.

Your ad server's existing facilities for forecasting and automatic optimization can be fully leveraged. As a result, you can minimize waste from over buffering while minimizing risk of under delivery. This solution can minimize the amount of time ad ops needs to monitor campaigns with viewability or brand safety goals and unlock opportunities to sell segments of high quality inventory to advertisers at a premium.

Additionally, Publisher Optimization supports Keyword exclusion list segments which are negative keyword lists.

See the Publisher Optimization Implementation Guide for more information.

Prebid JS Overview

Header bidding is running supply-side platform (SSP) and ad exchange code directly on a web page so publishers can receive bids on their inventory that may be unavailable through their primary ad server and exchange. The returned bids are then passed into the ad server so the bids can compete with direct demand and the primary ad server's exchange on a level playing field. Prebid JS is an open source library that helps publishers implement header bidding.

At a more in-depth detail, before calling the ad server, all the ad slots are sent to the enabled SSPs with a mapping of all the ad slots. The SSPs send a request to their demand-side platforms (DSPs) and each DSP returns a winning bid. Then Prebid JS sends to the ad server the highest winning bid as a bundle of 3 key/values.

Prebid intro

The IAS Publisher Optimization Prebid JS RTD Module supports the Prebid.org Real-Time Data (RTD) core module to add data to bid requests or add targeting values for the primary ad server. The IAS Publisher Optimization Prebid JS RTD Module lets you register and modify bid request/response and/or set targeting data for the publisher's ad server. IAS added a realTimeData module to the adapter to enable RTD. See the section 'Real-Time Data' for more information.

Real-Time Data

You need to setConfig with the RTD module which sets the publisher ID.

pbjs.setConfig({
realTimeData: {
auctionDelay: 200,
dataProviders: [
{
name: "ias",
waitForIt: true,
params: {
pubId: "1234"
}
}
]
}
});

Renamed key-values

Starting with Prebid JS version 6.19.0, IAS supports custom keys for IAS key-values. To use these custom keys (which are only needed if there is a collision between one of the IAS standard key-values, and another key-value), use the optional keyMappings configuration parameter.

The keyMappings parameter must be an object, whose properties correspond to the IAS key-values that you want to rename. The value associated to each property is a string with the new key (renamed).

Example

pbjs.setConfig({
realTimeData: {
auctionDelay: 200,
dataProviders: [
{
name: "ias",
waitForIt: true,
params: {
pubId: "1234",
keyMappings: {
'id': 'ias_id'
}
}
}
]
}
});

Custom URL

Example

pbjs.setConfig({ realTimeData: { auctionDelay: 200, dataProviders: [ { name: "ias", waitForIt: true, params: { pubId: "1234", pageUrl: "https://www.integralads.com/test" } } ] } });

Version 7.16 supports the optional configuration for specifying the URL to analyzed for brand safety and suitability purposes.

This solves an issue encountered by ad networks, who were previously unable to use the IAS brand safety and suitability key-values when their slots were added to their partners' pages by means of iframes. To use this feature, use the optional pageUrl configuration parameter. You can populate pageUrl with a string containing the URL to be analyzed, including the protocol. Only http and https URLs are supported. An empty string, a malformed URL in the string (for example a missing protocol) or a URL with a different protocol causes the adapter to ignore the parameter and revert to its default behavior (using document.location.href).

Ad Unit Path Mapping

Starting with Prebid JS version 7.21, IAS supports the optional configuration for custom mappings for the ad unit path. Such mappings allow IAS's clients to ensure that PreBid JS is able to communicate the correct ad unit path to IAS, even when external factors make it difficult to retrieve automatically. To use these mappings, use the optional adUnitPath configuration parameter.

The adUnitPath parameter must be an object, whose properties correspond to the slot IDs found on the page. The value associated to each property is a string with the ad unit path for that slot.

Example

dataProviders: [
{
name: "ias",
waitForIt: true,
params: {
pubId: "1234",
adUnitPath: {
'a-div-id': '/012345/ad/unit/path',
'another-div-id': '/012345/another/ad/unit/path'
}
}
}
]

Implementation Steps

IAS recommends upgrading your Prebid JS library to version 6.19.0 (and above). If you need an older version, the IAS RTD adapter is available from version 5.17 (and above), with a known issue that causes Prebid to wait the full auctionDelay timeout before calling the bidders. Version 6.19.0 solves this issue. Be certain to synchronize your integration with supported features in the version you are using.

IAS recommends all recommended Prebid modules are included in the client's Prebid library. Also, IAS requires the GPT Pre-Auction module.

See https://docs.prebid.org/download.html for more information on the modules.

IAS Preparation Steps

Prior to the implementation, ensure:

  • The IAS monitoring tag is on all your properties concerned by this implementation for more than 15 days

  • Prebid JS is implemented on all your properties concerned by this implementation

  • In your ad manager (for example, DFP) account, go to the Inventory section and define the following key/values pairs precisely:

DFPPreBid

Prebid JS

Prebid JS is JavaScript that must be placed on all publisher's webpages, in the header or through a Tag Management System, after the ad slots from the ad server are declared but before the call to the ad server is done, so that key/values can be sent.

Disable the Initial Loading

You need to disable the initial loading of your ad server if this is an a sync ad server, before the ad slots are defined.

<script async='async' src='./prebid.js'></script>
<script>
googletag.cmd.push(function() {
googletag.pubads().disableInitialLoad();
});
</script>

Callbacks and Timeouts

Finally, review the callback function that deals with the targeting in the ad server and the launch of the ad server. To enable RTD in the IAS Prebid JS module, you need to set the config for realTimeData for Prebid JS. A best practice is to use a time-out function to send the request to the different bidder's servers through the Prebid JS push function.

function sendAdserverRequest() {
if (pbjs.adserverRequestSent)
return;
pbjs.adserverRequestSent = true;
googletag.cmd.push(function() {
pbjs.que.push(function() {
pbjs.setTargetingForGPTAsync();
googletag.pubads().refresh();
});
});
}
setTimeout(function() {
sendAdserverRequest();
}, PREBID_TIMEOUT);
pbjs.que.push(function() {
// add RTD
pbjs.setConfig({
realTimeData: {
auctionDelay: 200,
dataProviders: [
{
name: "ias",
waitForIt: true,
params: {
pubId: "1234"
}
}
]
}
});
googletag.cmd.push(function() {
pbjs.que.push(function() {
pbjs.addAdUnits(adUnits);
pbjs.requestBids({
bidsBackHandler: sendAdserverRequest
});
});
});

Ad server

In your ad server, target the usual IAS key/values, just like for IAS's Publisher Optimization product.

See the Publisher Optimization guide for more information on the key/values to set up on the ad server:

  • Brand Safety

  • Context Control

  • Invalid Traffic

  • Viewability

For more info on deals through Prebid JS, see http://prebid.org/adops/deals.html.

Troubleshooting

You can use the built-in ?pbjs_debug=true parameter in the URL to see extra logs in your browser's console.

You can also filter the Network tab of your browser by /prebid.js|pub\?anId|gampad/ (for DFP) to see the call to Prebid JS, the call to IAS's servers and the response, and the call to DFP.

From there, the troubleshooting is similar to what has to be done for Publisher Optimization.

Complete Google Ad Manager sample code:

<html>
<head>
<script async='async' src =
'https://www.googletagservices.com/tag/js/gpt.js'></script>
<script>
var googletag = googletag || {};
googletag.cmd = googletag.cmd || [];
</script>
<script async='async' src='./prebid.js'></script>
<script>
googletag.cmd.push(function() {
googletag.pubads().disableInitialLoad();
});
</script>
<script>
googletag.cmd.push(function() {
googletag.defineSlot('/57514611/user/pub_opt/'
+ 'top_banner',
[
[970, 250],
[728, 90],
[1000, 90]
],
'div-gpt-ad-1492761750660-0').
addService(googletag.pubads());
googletag.defineSlot('/57514611/user/pub_opt/'
+ 'top_rectangle',
[
[300, 250],
[300, 600]
], 'div-gpt-ad-1492761750660-1').
addService(googletag.pubads());
googletag.defineSlot('/57514611/user/pub_opt/'
+ 'mid_rectangle',
[
[300, 250],
[300, 600]
], 'div-gpt-ad-1492761750660-2').
addService(googletag.pubads());
googletag.pubads().enableSingleRequest();
googletag.enableServices();
});
</script>
<script>
var PREBID_TIMEOUT = 700;
var adUnits = [{
code: 'div-gpt-ad-1492761750660-0',
sizes: [[970, 250], [728, 90], [1000, 90]],
bids: [{
}]
function sendAdserverRequest() {
if (pbjs.adserverRequestSent) return;
pbjs.adserverRequestSent = true;
googletag.cmd.push(function() {
pbjs.que.push(function() {
pbjs.setTargetingForGPTAsync();
googletag.pubads().refresh();
});
});
}
setTimeout(function() {
sendAdserverRequest();
}, PREBID_TIMEOUT);
pbjs.que.push(function() {
// add RTD
pbjs.setConfig({
realTimeData: {
auctionDelay: 200,
dataProviders: [
{
name: "ias",
waitForIt: true,
params: {
pubId: "1234"
}
}
]
}
});
googletag.cmd.push(function() {
pbjs.que.push(function() {
pbjs.addAdUnits(adUnits);
pbjs.requestBids({
bidsBackHandler: sendAdserverRequest
});
});
});
</script>
</head>
<body>
<!-- /57514611/user/pub_opt/top_banner -->
<div id='div-gpt-ad-1492761750660-0'>
<script>
googletag.cmd.push(function() {
googletag.display('div-gpt-ad-1492761750660-0');
});
</script>
</div>
<!-- /57514611/user/pub_opt/top_rectangle -->
<div id='div-gpt-ad-1492761750660-1'>
<script>
googletag.cmd.push(function() {
googletag.display('div-gpt-ad-1492761750660-1');
});
</script>
</div>
<!-- /57514611/user/pub_opt/mid_rectangle -->
<div id='div-gpt-ad-1492761750660-2'>
<script>
googletag.cmd.push(function() {
googletag.display('div-gpt-ad-1492761750660-2');
});
</script>
</div>
</body>
</html>

Changelog

Minimum Version

Notes

5.17

Basic functioning without any newer feature and a minor bug that causes the adapter to wait for the whole timeout allotted to the module.

6.19

Corrected a timeout bug of v. 5.17+. Added support for renaming the IAS key-values before sending them to the adserver.

7.16

Add support for specifying the URL that has to be analyzed for brand safety and suitability purposes.

7.21

Add support for mapping the slot ID to the ad unit path.


Was this article helpful?

Need further help?

Create an IAS case with details of your inquiry to receive help from our internal support team.