Sub-modules interact with the Real-Time Data (RTD) core module to add data to bid requests or add targeting values for the primary ad server.
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.
See the Publisher Real-Time Data Configuration reference for more information.
Your module should not look at the values of the auctionDelay or waitForIt flags - just do what needs to be done as fast as possible. It’s ok to ask publishers in your documentation to give you a certain amount of time or to flag your module as important, but it’s not ok for the code to require it.
The RTD-core infrastructure uses hooks and event listeners to call the appropriate sub-modules to retrieve the data. Here is the flow for how the RTD-core module interacts with its sub-modules:
The activities performed by the RTD-core module are on the left-hand side, while the functions that can be provided by your RTD sub-module are on the right-hand side. Note that you don’t need to implement all of the functions - you’ll want to plan out your functionality and develop the appropriate functions.
When you create a Real-Time Data sub-module, you will be operating under the umbrella of the Real-Time Data core module. Here are the services core provides:
Working with any Prebid project requires using Github. In general, we recommend the same basic workflow for any project:
RTD sub-modules are subject to a number of specific technical rules. Please become familiar with the module rules that apply globally and to Real Time Data modules in particular.
Create a markdown file under modules
with the name of the module suffixed with ‘RtdProvider’, e.g., exRtdProvider.md
Example markdown file:
# Overview
Module Name: Ex Rtd Provider
Module Type: Rtd Provider
Maintainer: prebid@example.com
# Description
RTD provider for Example.com. Contact prebid@example.com for information.
Now create a javascript file under modules
with the name of the module suffixed with ‘RtdProvider’, e.g., exRtdProvider.js
In order to let RTD-core know where to find the functions in your sub-module, create an object called submoduleObj
that contains key values:
param name | type | Scope | Description | Params |
---|---|---|---|---|
name | string | required | must match the name provided by the publisher in the on-page config | n/a |
gvlid | number | optional | global vendor list ID for your submodule | n/a |
init | function | required | defines the function that does any auction-level initialization required | config, userConsent |
getTargetingData | function | optional | defines a function that provides ad server targeting data to RTD-core | adUnitArray, config, userConsent |
getBidRequestData | function | optional | defines a function that provides bid request data to RTD-core | reqBidsConfigObj, callback, config, userConsent |
onAuctionInitEvent | function | optional | listens to the AUCTION_INIT event and calls a sub-module function that lets it inspect and/or update the auction | auctionDetails, config, userConsent |
onAuctionEndEvent | function | optional | listens to the AUCTION_END event and calls a sub-module function that lets it know when auction is done | auctionDetails, config, userConsent |
onBidRequestEvent | function | optional | listens to the BID_REQUESTED event and calls a sub-module function that lets it know when a bid is about to be requested | bidRequest, config, userConsent |
onBidResponseEvent | function | optional | listens to the BID_RESPONSE event and calls a sub-module function that lets it know when a bid response has been collected | bidResponse, config, userConsent |
For example:
export const subModuleObj = {
name: 'ExampleRTDModule',
init: init,
getTargetingData: sendDataToModule
};
Register submodule to RTD-core:
submodule('realTimeData', subModuleObject);
Several of the interfaces get a userConsent
object. It’s an object that carries these attributes:
These are provided so you can do the right thing with respect to regulations. The only privacy requirement imposed by the RTD-core is that sub-modules make make use of the StorageManager instead of attempting to access cookies or localstorage directly.
false
, the submodule will be ignored.See the Building the Request section of the Bid Adapter documentation for more details about GDPR and USP.
This is the function that will allow RTD sub-modules to merge ad server targeting data into the auction. It’s called at the AUCTION_END event for each auction.
{
"slotA":{
"p":0.56, // ad server targeting variable (e.g. p) for slotA is 0.56
},
"slotB":{
"p":0.824, // ad server targeting variable (e.g. p) for slotB is 0.824
}
}
Code Example
/** @type {RtdSubmodule} */
export const subModuleObj = {
name: 'ExampleRTDModule',
init: init,
getTargetingData: returnTargetingData
};
function init(config, userConsent) {
// do init stuff
if (initfailed) return false;
return true;
}
function returnTargetingData(adUnits, config, userConsent) {
// do stuff
return data;
}
submodule('realTimeData', subModuleObj);
This is the function that will allow RTD sub-modules to modify the AdUnit object for each auction. It’s called as part of the requestBids hook.
pbjs.requestBids
(see below). Note that several auctions can happen concurrently, so the sub-module must be ready to support this.reqBidsConfigObj
as shown below
The reqBidsConfigObj
parameter is a copy of the object passed to requestBids
, except for:
adUnits
and timeout
are always defined (if the publisher didn’t provide them, the default values are filled in - pbjs.adUnits
and getConfig('bidderTimeout')
respectively)ortb2
is replaced with an ortb2Fragments
object, intended to be inspected and / or modified by your module.The ortb2Fragments
parameter is an object containing two properties:
global
, an object containing global (not bidder-specific) first party data in the same OpenRTB format used by setConfig({ortb2})
bidder
, a map from bidder code to bidder-specific, OpenRTB-formatted first party data.Your module may modify either or both with additional data. If adding bidder-specific data in ortb2Fragments.bidder
, it should also support a parameter to allow the publisher to define which bidders are to receive the data.
Before version 7, the pattern for first party data inspection and enrichment by RTD modules was getConfig({ortb2])
/ mergeConfig({ortb2})
. With the introduction of auction-specific data in 7, the global getConfig('ortb2')
is “frozen”
at the time requestBids
is called, and RTD submodules that wish to modify it are required to work on ortb2Fragments
instead - as any additional call to mergeConfig
will only take effect on the next auction.
Code Example
/** @type {RtdSubmodule} */
export const subModuleObj = {
name: 'ExampleRTDModule2',
init: init,
getBidRequestData: alterBidRequests
};
function init(config, userConsent) {
// do init stuff
if (initfailed) return false;
return true;
}
function alterBidRequests(reqBidsConfigObj, callback, config, userConsent) {
// do stuff
// put data in adUnits' ortb2Imp:
reqBidsConfigObj.adUnits.forEach((adUnit) => mergeDeep(adUnit, 'ortb2Imp.ext', myCustomData);
// or in global first party data:
mergeDeep(reqBidsConfigObj.ortb2Fragments.global, myCustomData);
// or in bidder-specific first party data:
config.bidders.forEach((bidderCode) => mergeDeep(reqBidsConfigObj.ortb2Fragments.bidder, {[bidderCode]: myCustomData});
callback();
}
submodule('realTimeData', subModuleObj);
AUCTION_INIT
, AUCTION_END
, and BID_RESPONSE
.Code Example
Here is a code example with both mandatory and optional functions:
/** @type {RtdSubmodule} */
export const subModuleObj = {
name: 'ExampleRTDModule3',
init: init,
onAuctionInitEvent: onAuctionInit,
onAuctionEndEvent: onAuctionEnd,
onBidRequestEvent: onBidRequest,
onBidResponseEvent: onBidResponse
};
function onAuctionInit(auctionDetails, config, userConsent) {
// inspect/update auction details
}
function onAuctionEnd(auctionDetails, config, userConsent) {
// take note of auction end
}
function onBidRequest(bidRequest, config, userConsent) {
// optionally update bidRequest
}
function onBidResponse(bidResponse, config, userConsent) {
// optionally update bidResponse
}
function init(config, userConsent) {
// do init stuff
if (initfailed) return false;
return true;
}
function beforeInit(){
//take actions to get data as soon as possible
submodule('realTimeData', subModuleObj);
}
beforeInit();
Create a JS file under test/spec/modules
with the name of the bidder suffixed with ‘RtdProvider_spec’, e.g., exRtdProvider_spec.js
Write great unit tests. See the other RtdProvider_spec.js
files for examples.
Once everything looks good, submit the code, tests, and markdown as a pull request to the Prebid.js repo.
Create a fork of the website repo and a branch for your new adapter. (e.g. feature/exRtdProvider)
Create a new file for your RTD sub-module in dev-docs/modules/ExampleRtdProvider.md. Take a look at the other *RtdProvider.md files in that directory for the important header values. Specifically it requires the following:
---
layout: page_v2
title: Example Module
display_name: Example
description: Useful statement for what this does
page_type: module
module_type: rtd
module_code : example
enable_download : true
sidebarType : 1
---
# Example Module
[Useful publisher-facing documentation]
Submit the pull request to the prebid.github.io repo.
We sometimes get pretty busy, so it can take a couple of weeks for the review process to complete, so while you’re waiting, consider joining Prebid.org to help us out with code reviews. (!)