Introduction
Hello!
This document will lead you through the integration process with
RTB House's Outstanding Prebid Ways so you can begin
your RTB House prebid campaign.
RTB House provides a piece of code to be added in the
header of the page before the ad server callout.
It generates an
asynchronous call so RTB House can identify the user and return a bid.
Such information including the bid price is then sent to the adserver.
RTB House campaigns are targeted in the adserver based on Custom keyword criteria.
Requirements
What will you receive from RTB House:
- Individual Publisher ID
- Code samples demonstrating how to initialize the RTB House adapter and how to map the placements
- Optional creative codes that may be used in the adserver, by default we suggest using default prebid codes
- Access to individual Data Studio dasboard with statistics
We will need you to
- Implement clear and transparent prebid scripts on the page
- Map the placements available on each page and use it to initialize our adapter
- Create the line items for the different bid prices in your adserver
- Implement the targeting rules and the creative code
- Comply with IAB Consent Framework as RTB House do. Please refer to their documentation for more information and examples of certified CMPs.
Scripts Implementation
Prebid.js - adapter and modules
The code initializes the RTB House tags, which are a part of prebid
A.B.C.js (A,B,C being current version numbers). The code will load the
prebidA.B.C.js library and will also build the events
queue that will be used later.
Prebid.js package contatins all the chosen bidder adapters and all the
modules in one JS file, it can be customized and downloaded from
For this particular setup purpose we have enabled:
Bidder Adapters:
- RTB House
Analytics Adapters:
- None
Modules:
- Currency
- TCF Consent Management (GDPR)
- US Privacy Consent Management - US Privacy
- User ID: SharedID
- DSA Control Module
The loader request is asynchronous and is cached on the user browser.
Apart from prebid.js package version - No code changes are required on
this section.
The next step is to map all the adunits available on the page and assign their code.
In this section you will see how the typical minimalistic display adunit is set up.
| Parameter | Description |
|---|---|
| code | Unique identifier that you create and assign to the ad unit. Used to set query string targeting on the ad. If using GPT, we recommend setting simillar "code" as a slot element ID. |
| mediaTypes | banner, native or video |
| banner.sizes | Here you can set acceptable adunit sizes, in example in variable. |
| bidder | Required, name of the bidder - "rtbhouse" |
| params.region | Required, type: string, region of specific publisher is being assigned by RTB House Inventory team (-eu, -asia, -us). |
| params.publisherId | Required, type: string, unique ID assigned by RTB House Inventory team. |
| params.bidfloor | Optional, type: float, Minimal CPM value in USD currency [note: it is always USD; You should use the Currency module whenever possible] |
Bid response details
The mapping is used to generate a bid request to RTBhouse's
endpoint.
In case RT House has a bid for the user, the request will return a
HTTP STATUS 200 with an bids object
described below :
| Field | Type | Description | Example |
|---|---|---|---|
| id | String | The adunit id provided in the request | ad-unit-0 |
| impid | String | Impression individual Id | 1958db31f122811 |
| price | Float | The raw bid CPM | 1.58 |
| adid | String | Creative Id | l2HjtZ8tLkRPAaeVkRk0 |
| adm | String | The creative iframe |
<iframe
src=\"https://sin.creativecdn.com/imp-delivery?tkn=EdN...>
|
| adomain | List of Strings | The domain name | ["rtbhouse.com"] |
| cid | String | The deal Id | ...z3XR2NmqbMmZl... |
| w | Integer | The creative width | 300 |
| h | Integer | The creative height | 250 |
Please find an example of such object below:
In case the user is not eligible to any RTBhouse campaign, the bid response will be an empty 204 response.
Header implementation
Disabling the adserver auto load
The original DFP tags are similar to below.
Since we will wait for the RTBhouse Bidder Call before calling the
adserver, the function:
googletag.pubads().disableInitialLoad() and
googletag.pubads().enableSingleRequest(), can be placed
anywhere before googletag.enableServices(). Another thing
worth remembering is adding apropriate
"/DFPCode/AdUnitCode/Custom_label" as the first parameter value in
.defineSlot method.
The callback function is executed as soon as the bid response is received. The bids must now be processed and sent within the adserver request. The examples from now on will use DFP/GAM as reference, but it can be adapted to any adserver that supports keyword targeting.
The adserver request must wait for the RTB House bidder to respond first. It can be achieved by using a combination of two functions:
-
disableInitialLoad(): will prevent the Adserver to be charged automatically as the page loads -
googletag.pubads().refresh(): will be used to finally trigger the adserver call after the RTBhouse bid response or if the timeout is reached
More details on DFP's documentations here.
Sending the keywords
First we are adding adUnits, then implementing a function for
initializing the Adserver. Then we add:
pbjs.setTargetingForGPTAsync &&
pbjs.setTargetingForGPTAsync();
- part which will append RTBhouse keywords to the adserver call.
googletag.pubads().refresh();
- part which will trigger the adserver call.
Sending keywords back to adserver can be implemented in the callback
function that will be triggered once the RTB House bid response is
received (or after the timeout). On our previous example, we are using
the function named
initAdserver.
-
pbjs.requestBids({...})triggers the bid request to external bidders. -
initAdserveris executed at most in the number of ms defined in variable PREBID_TIMEOUT. -
The auxiliary function
pbjs.setTargetingForGPTAsync()automatically parses the response and sends placement-level keywords to the adserver :
| Keyword | Type | Description | Example |
|---|---|---|---|
| hb_pb | String | The general bid price band CPM | hb_pb=0.40 |
| hb_pb_rtbhouse | String | (optional) The bid price band CPM for RTBHouse | hb_pb_rtbhouse=0.40 |
| hb_bidder | String | (optional) Selecting RTBHouse bidder | hb_bidder=rtbhouse |
Above table presents two ways of setting up keywords:
- First is setting up just hb_pb keyword and it will work in all cases
- Second one, setting up all three keywords (first one and both optional ones), and then the line items will only work with RTB House bidder
Prebid Modules
In this section additional modules will be described. All the modules
are defined in
pbjs.setConfig({})
Currency module
This module supports the conversion of multiple bidder currencies into a single currency used by the publisher's ad server. This module allows, gaining automatic updates as currency exchange rates fluctuate. Here's how it works at a high level:
- A Prebid.js package is built that contains the extra currency module code
- Config in the page defines the currency used by the Publisher's ad server and other configuration parameters.
- The existence of this configuration causes the Prebid platform to load a currency conversion file while the bids are taking place. Alternately, the conversion rates can be provided in the page.
- At runtime, bids are converted to the ad server currency as needed.
- Default rates can be provided in case the file cannot be loaded.
Currency module is used to translate currency of the adserver to match currency of a bidder, if there is no other script doing such translations, it is higly recommended to implement Currency module.
| Parameter | Type | Description |
|---|---|---|
| priceGranularity | String dictionary | Tells the ad server how much money the “bidder” demand is worth. Allowed values are "low, "med", "high"m "auto", "dense". Detailed description. |
| currency.adServerCurrency | String | ISO 4217 3-letter currency code. If this value is present, the currency conversion feature is activated. |
| currency.granularityMultiplier | Decimal | How much to scale the price granularity calculations. Defaults to 1. Is used for currencies that are not changing at the same rate - their value is far from USD [close to 1:1], it can be changed for example for markets like YEN to USD [110:1] |
| currency.defaultRates | Object | An optional parameter that defines a default rate that can be used if the currency file cannot be loaded. This option isn’t used when the rates parameter is supplied. Example: { USD: { PLN: 4 } } |
| currency.rates | Object | This optional argument allows you to specify the rates with a JSON object, subverting the need for the conversionRateFile parameter. If this argument is specified, the conversion rate file will not be loaded. Example: { ‘USD’: { ‘CNY’: 6.8842, ‘GBP’: 0.7798, ‘JPY’: 110.49 } } |
| currency.conversionRateFile | URL | Optional path to a file containing currency conversion data. See below for the format. Prebid.org hosts a file as described in the next section. |
Please find an example for PLN based GAM below:
URL: https://docs.prebid.org/dev-docs/modules/currency.htmlConsent management modules
Consent management modules are designed to support the EU General Data
Protection Regulation (GDPR) and to support the California Consumer
Privacy Act (CCPA). The IAB has generalized these guidelines to cover
future regulations, referring to the feature as “Global Privacy Platform (GPP)”
GDPR Consent management module works with supported Consent
Management Platforms (CMPs) to fetch an encoded string representing
the user's consent choices and make it available for adapters to
consume and process.
To utilize Consent management module, a CMP
(Consent Management Platform) compatible with the IAB TCF 2.0 or 2.2 spec
needs to be implemented on the site to interact with the user and
obtain their consent choices. We do recommend to that you place the
CMP code before the Prebid.js code in the head of the page in order to
ensure the CMP’s framework is loaded before the Prebid code executes.
For detailed manual refer to the official Prebid documentation pages:
TCF Consent Management Module
and
US Privacy Consent Management Module
| Parameter | Type | Description |
|---|---|---|
| cmpApi | String | Set to default, as 'iab'or 'static' for a non-standard IAB integrations |
| timeout | Integer | CMP response timeout, defaults to 5000ms |
| allowAuctionWithoutConsent | Boolean |
Defines what happens when obtaining consent info from CMP fails
(suppresses auction). In example scenario, which is not linked
with any CMP, it is set to "true"
See tcfControl Prebid module for detailed management of consents. |
| defaultGdprScope | Boolean | Defines what the gdprApplies flag should be when the CMP doesn’t respond in time
or the static data doesn’t supply. Defaults to false. |
| Parameter | Type | Description |
|---|---|---|
| cmpApi | String |
The USP-API interface that is in use. Supported values are ‘iab’ or ‘static’.
Static allows integrations where IAB-formatted strings are provided in a non-standard way.
Default is 'iab'.
|
| timeout | Integer | Length of time (in milliseconds) to allow the USP-API to obtain the CCPA string.
Default is 50.
|
| consentData | Object | An object representing the CCPA notice and opt-out status
data being passed directly; only used when cmpApi is ‘static’.
Default is undefined. |
Publishers not using an IAB-Compliant CMP - head directly to the URL provided below.
URL: https://docs.prebid.org/dev-docs/modules/consentManagementTcf.htmlUser ID: SharedID module
User ID module stores an unique user id in the first party domain and makes it accessible to all adapters. Similar to IDFA and AAID, this is a simple UUID that can be utilized to improve user matching, especially for iOS and MacOS browsers, and is compatible with ITP (Intelligent Tracking Prevention). It's lightweight and self contained. Adapters that support SharedID will be able to pick up the user ID and return it for additional server-side cross device tracking. There is no special registration or configuration for SharedID. Each publisher's privacy policy can take SharedID into account.
| Parameter | Type | Description |
|---|---|---|
| storage | Object | The publisher can specify some kind of local storage in which to store the results of the call to get the user ID. It can be either cookie or HTML5 storage. This is not needed when value is specified or the ID system is managing its own storage |
| storage.type | String | Required "cookie" or "html5" |
| storage.name | String | Create a cookie with this name - The name of the cookie or html5 local storage where the user ID will be stored |
| storage.expires | Integer | How long the user ID info will be stored |
| storage.refreshInSeconds | Integer | The amount of time (in seconds) the user ID is be cached in storage before calling the provider again to retrieve a potentially updated value for their user ID. If set, this value can equate to a time period less than the number of days defined in storage.expires. By default the ID will not be refreshed until it expires |
| value | Object | Used only if the page has a separate mechanism for storing a User ID. The value is an object containing the values to be sent to the adapters |
Adserver setup
Setting up an ad server, requires 5 basic steps, which are:
- Set up key-values
- Set up an order
- Set up first line item
- Set up a creative
- Set up rest of the line items
Keywords
Go to Inventory > Key-values and click on
New Key and create the key-value
- Key name:
hb_pbandhb_pb_rtbhouse - Value type: Users will enter targeting values when creating line items or checking inventory. (Dynamic)
Order
Go to Delivery > Orders and click on
New Order and create one new Order for the campaign.
First Line Item
You can create the first line on the same page or simply by entering any created order. The goal is to create one dedicated line item per different CPM price band. For the best performance one every each 0.01.
We will create the unitary CPM for the first line item:
- Choose "Display" Ad type
-
Name: Please use a self-explanatory name like
campaign_name_1.00 - Line item type: It depends on your business goals, we will set it to "Standard".
- Priority: Please select the priority as agreed with your RTB House representative. In example we set "Standard" but it is worth to mention that Prebid recommends to use Price Priority.
-
Expected creatives: Please include all formats available on your
page. Eg:
728x90,300x250
-
Labels section: Please check
Allow same advertiser exception
- Start time:
Immediately - End time:
Unlimited -
Quantity:
Unlimited - plesae put there a very high number -
Rate: Please include here the CPM. On this first example we use
0.01PLN, but recommended currency is USD.
- Display Creatives:
One or More. - Rotate Creatives:
Evenly
Finally, please select the inventory for the campaign and add the following targeting:
- Type: Choose
Key-values - Select a key: Choose
hb_pb - Value: choose
isand input0.01
Finally, hit save and follow with the creative steps
below.
Creatives
Please find example prebid creative code below:
To prepare a new creative, go to Delivery >
Creatives > and click on
Add creative then type and select the same advertiser
name to add creative (for us Prebid (Advertiser)). Hit Select and:
- Type:
Pick Third-party -
Name:
Type_name_that_enables_easy_identification -
Target ad unit size:
Pick sizes that you wish to target according to the ad unit or pick 1x1 - this allows us to set up size override, which allows this creative to serve on all inventory sizes. -
Code type and snippet:
Pick standard and paste the code located above
Click Save.
Go back to the first line item created, click on the
Creatives tab and on
Add creative - Existing creative.
Pick the one that was just created.
The last step is to duplicate the creative so its quantity equals the number of unique ad units you have on the same page. I.e.: Should you have up to 5 different ad units on your homepage, it means you will need to setup at least 5 creatives for the line item.
The easiest way to achieve this is by selecting one (or multiple)
creatives and click on Copy creative that appears on the
blue bar, repeat until you have the minimum amounts required for line
item to work.
Remaining line items
Now that you have the first line item fully configured, you can simply
duplicate it and reuse the existing creatives. To do so, go to the
line item pages, select its respective checkbox and click on
Copy and share creatives that will appear on the blue
bar. Repeat the action for all the different price bands you have.
Please don't forget to update:
- The line item name
- The CPM
- The keyword targeting the respective price band
You can edit those values directly from the list page by clicking on the icon on the corner of each field:
- Line item name:
- CPM:
- Inventory and keyword targeting
- Start date. Please double check the value as the default one is the next day!
Once you are set, select all the new line items and click on the
Resume button.
For official prebid guide: URL: https://docs.prebid.org/adops/gam-hbt-step-by-step.html
Automatic line items creation
RTB House can offer to automatically set up all the orders, line items
along with creatives for you - using Line Item Creator App.
Please contact RTB House Inventory Support directly at
inventory_support@rtbhouse.com
to discuss requirements and the progression path.
Native ads
Native Placement
In order to activate Native demand, first you need to declare an appropriate adunit. Please find a short example below on how the basic adunit can be defined to build the native ad.
All the other parameters that could be passed and integrated into the
native you can find under this link:
URL: https://docs.prebid.org/prebid/native-implementation.html
Native Response
Below you can find an example of a native response:
When a native demand is available, RTBhouse will return the following native object:
Native Object
| Field | Type | Description |
|---|---|---|
| product | Product object Array | List of product assets. |
| advertiser | Advertiser object | Includes the adv name and logo |
| impression_pixels | Impression pixels object Array | List of impression pixels |
Product Object
| Field | Type | Description |
|---|---|---|
| title | String | Product title |
| description | String | Product description |
| click_url | String | Product landing page |
| call_to_action | String | Product CTA |
| image | Image object | Product image (WidthxHeight px) |
Image Object
| Field | Type | Description |
|---|---|---|
| url | String | Image URL. |
| height | Integer | Image height |
| width | Integer | Image width |
Advertiser Object
| Field | Type | Description |
|---|---|---|
| description | String | Advertiser name |
| domain | String | Advertiser domain |
| logo | Image object | Advertiser logo (WidthxHeight px) |
Privacy Object
| Field | Type | Description |
|---|---|---|
| optout_click_url | String | Opt-out landing page URL |
| optout_image_url | String | Adchoices icon URL |
Impression Pixel Object
| Field | Type | Description |
|---|---|---|
| url | String | Impression pixel beacon |
Adserver integration
The campaigns can be set up the same as in case of the standard ads,
but with 1x1 and "fluid" adunit sizes added.
In topic of creatives structure, you can find an example of native
creative code below:
RTB House Native guidelines:
- Implement the link to the opt-out page
- Display at least one advertiser information (domain, name)
- Display at least one product recommendation
- Use RTB House click URLs
- Every impression pixel must be called once the ad is delivered
Complete examples
You can find a fully working example of standard banners and native
placements on
this page.
Please check the source-code around the area of:
<!-- RTB House bidder -->
Native ads examples are available under these two links:
For an entry in ads.txt file please use:
RTBHOUSE.COM, {PUBLISHER ID}, DIRECT