Prebid.js Weborama Real-Time Data Submodule
- Mohamed Ibn Alkadi
Description
Weborama provides a Semantic AI Contextual API that classifies in Real-time a web page seen by a web user within generic and custom topics. It enables publishers to better monetize their inventory and unlock it to programmatic advertising.
Prebid.js is a feature-rich header bidding platform for the web, including more than 300 demand sources and 50 analytics adapters. It supports currency conversion, GDPR, common ID systems, and multiple ad servers.
Modules in the Real-Time Data (RTD) category conform to a consistent set of publisher controls. The publisher can choose to run multiple RTD modules, define an overall amount of time they’re willing to wait for results, and even flag some of the modules as being higher priority than others.
Weborama contributed to Prebid.js with a RTD submodule to handle contextual profile and set as Google Ad Manager (GAM) targeting.
Prebid.js Real Time Data Module Overview
The point of the Real Time Data (RTD) infrastructure is to make configuration consistent for publishers. Rather than having dozens of different modules with disparate config approaches, being a Real-Time Data sub-module means plugging into a framework for publishers to control how sub-modules behave. For example, publishers can define how long the auction can be delayed and give some sub-modules priority over others.
The RTD infrastructure is a generic module, not useful by itself. Instead, it allows sub-modules to register and modify bid request/response and/or set targeting data for the publisher’s ad server.
Publishers will decide which RTD sub-modules they want to use, and can set parameters like timeout, endpoints, etc. They will set limits on how long sub-modules are allowed to delay the auction, which will most likely be in the tens of milliseconds.
Source: https://docs.prebid.org/dev-docs/add-rtd-submodule.html#overview
Module Configuration
The minimal configuration needed for this submodule is the API token, unique by client, provided by Weborama. It is necessary build the Prebid.js with our submodule and the rtdModule as well
gulp build --modules=rtdModule,weboramaRtdProvider,...other...modules
To be used, we need to add our configuration to the section dataProviders like this:
pbjs.setConfig(
...
realTimeData: {
auctionDelay: 5000, // optional
dataProviders: [
{
name: "weborama",
waitForIt: true,
params: {
weboCtxConf: {
setTargeting: true,
token: "<<token provided by weborama>>",
targetURL: "..." // default is document.URL
}
}
}
]
}
...
}
For more information you can check https://docs.prebid.org/dev-docs/publisher-api-reference/setConfig.html#setConfig-realTimeData
Using Prebid.js without bid adapters
It is possible to use prebid.js without bid adapters, however the auction phase will be very fast and there will be no time to fetch the contextual profile from the API via asynchronous http request. For this case you should:
set a non-zero value (on milliseconds) for realTimeData.auctionDelay property
set the flag waitForIt as true for the weborama dataProvider
Parameter Descriptions for the Weborama Configuration Section
Here are some parameters to be used in weborama RTD module configuration. To access the latest version of these parameters, please check the official prebid.js documentation page.
Name | Type | Description | Notes |
name | String | Module name | Mandatory. Always “weborama”. |
waitForIt | Boolean | Required to ensure that the auction is delayed until prefetch is complete | Optional. Defaults to false but recommended to true |
params | Object | Optional | |
params.weboCtxConf | Object | Weborama Contextual Configuration | Optional |
params.weboCtxConf.token | String | Security Token provided by Weborama, unique per client | Mandatory |
params.weboCtxConf.targetURL | String | Url to be profiled in the contextual api | Optional. Defaults to document.URL |
params.weboCtxConf.defaultProfile | Object | Default value of the profile to be used when there are no response from contextual api (such as timeout) | Optional. Default is {} |
params.weboCtxConf.setTargeting | Boolean | If true, will use the contextual profile to set the GAM targeting of all adunits managed by prebid.js | Optional. Default is true. |
params.weboCtxConf.setOrtb2 | Boolean | If true, will use the contextual profile to set the ortb2 configuration on site.ext.data | Optional. Default is false. |
Module Usage
If the module configuration contains the contextual api token, we will use it to fetch the contextual profile of the targeting url in the init phase. Then, in the getTargeting phase we will set the targeting (webo_ctx and webo_ds keys) on each adunit handled by Prebid.
Module build
From Prebid.js download page
The easiest way to use the weborama RTD submodule is from the prebid.js download page. Just check all modules and bid adapters needed including the Vendor Specific Module “Weborama Real-time Segmentation Module”. Please specify the minimal Prebid.js version 5.15.0
and click Get Prebid.js! at the bottom of the page.
From source code (more advanced)
The weborama RTD submodule is available since prebid.js version 5.15.0
We can follow the instructions to build a standalone version of the prebid.js via gulp and add the weborama module.
$ gulp build --modules=rtdModule,weboramaRtdProvider,...other modules…
this will generate a build/dist/prebid.js will all modules defined in the command line, minified in one single file. Including other modules or bid adapters is optional.
to test we should use a html static page like this:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml ">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
</head>
<body>
<script async src="https://securepubads.g.doubleclick.net/tag/js/gpt.js"></script>
<script src="path/to/standalone/prebid.js" async></script>
<script>
var pbjs = pbjs || {};
pbjs.que = pbjs.que || [];
pbjs.que.push(function() {
pbjs.setConfig({
debug: true,
realTimeData: {
auctionDelay: 5000, // optional
dataProviders: [
{
name: "weborama",
waitForIt: true,
params: {
weboCtxConf: {
setTargeting: true,
token: "<to be defined>",
targetURL: "<page to be profiled>",
defaultProfile: {
webo_ctx: ['optionalSegment...']
}
}
}
}
]
}
});
});
</script>
<script>
var div_1_sizes = [
[300, 300]
];
var PREBID_TIMEOUT = 3000;
var FAILSAFE_TIMEOUT = 5000;
var adUnits = [{
code: '/1056029/webo-ctx-prebid',
mediaTypes: {
banner: {
sizes: div_1_sizes
}
},
bids: [{ /* specific bid conf */}]
}];
// ======== DO NOT EDIT BELOW THIS LINE =========== //
var googletag = googletag || {};
googletag.cmd = googletag.cmd || [];
googletag.cmd.push(function() {
googletag.pubads().disableInitialLoad();
});
var pbjs = pbjs || {};
pbjs.que = pbjs.que || [];
pbjs.que.push(function() {
pbjs.addAdUnits(adUnits);
pbjs.requestBids({
bidsBackHandler: initAdserver,
timeout: PREBID_TIMEOUT
});
});
function initAdserver() {
if (pbjs.initAdserverSet) return;
pbjs.initAdserverSet = true;
googletag.cmd.push(function() {
pbjs.que.push(function() {
pbjs.setTargetingForGPTAsync();
googletag.pubads().refresh();
});
});
}
// in case PBJS doesn't load
setTimeout(function() {
initAdserver();
}, FAILSAFE_TIMEOUT);
googletag.cmd.push(function() {
googletag.defineSlot('/1056029/webo-ctx-prebid', div_1_sizes, 'div-gpt-ad-1620653642627-0').addService(googletag.pubads());
googletag.pubads().disableInitialLoad();
googletag.enableServices();
});
</script>
<article>
<p>
test webo ctx using prebid.js
</p>
</article>
<h2>Basic Prebid.js Example</h2>
<h5>Div-1</h5>
<div id='div-gpt-ad-1620653642627-0' style='width: 300px; height: 300px;'>
<script type='text/javascript'>
googletag.cmd.push(function() {
googletag.display('div-gpt-ad-1620653642627-0');
});
</script>
</div>
<button onclick="googletag.cmd.push(function() { googletag.pubads().refresh(); });">
Show/Refresh Ad
</button>
</body>
</html>