Introduction

Hello!
This document will lead you through the integration process with RTB House's Prebid Server endpoint.

RTB House provides a publicly available Prebid Server adapter and all related files (config files, test files etc.) as a part of Prebid.org's Prebid Server Open Source Project.

Requirements

What will you receive from RTB House:

• Individual Cookie Matching Endpoint ID (INTEGRATION_ID)
• Individual publisher ID (or IDs for multiple publishers) related to the prebid server integration (publisherId)

We will need you to

• Provide exactly one valid active cookie matching endpoint regardless of web page (unless indicated otherwise)
• Get the latest version of the Prebid Server repository
• Apply the described below modifications
• Compile, run and test the new instance
• Configure your Prebid.js on-page scripts to use Prebid Server (see below)

Server-side integration

Important note

The below procedure is also valid for Prebid Server hosting companies working with multiple publishers or SSPs.

• RTB House needs to receive exactly one valid active cookie matching endpoint regardless of web page (unless indicated otherwise). The URL has to contain a dedicated parameter of which value will be filled in with the current user ID (UID) by our cookie matching endpoint.
• RTB House team creates cookie matching endpoint using the provided URL and generates an INTEGRATION_ID which needs to be placed in usersync.redirect.url parameter (for Java version) and in userSync.redirect.url parameter (for Go version) of the adapter configuration below

Cookie Mapping Procedure

Publisher Actions:

1. Confirm whether GDPR parameters will be provided (gdpr=0/1 and gdpr_consent=<consent string>). The publisher's endpoint URL may behave differently depending on user consent, for example rejecting requests with messages like GDPR is required for gdpr=1 or GDPR consent string is malformed.

2. Provide a functional cookie mapping endpoint URL. The endpoint URL, for example:

   https://cookie-mapping.publisher.com/setuid?bidder=rtbhouse&account=1234&f=i&gdpr=1&gdpr_consent=CQqRk...Lo.YAAAA&uid=test_cookie

   where uid has the literal value test_cookie, must consistently return an HTTP 200 or HTTP 204 status response.

3. If GDPR enforcement is active on the publisher endpoint, ensure the URL is tested using a valid consent string with appropriate flags enabled for all relevant vendors. RTB House uses Vendor ID 16. Select all relevant purposes and vendor flags.

Example:

• Navigate to https://iabgpp.com/.
• Switch to the TCF String tab.

• Select the tcfeu tab next to the header tab, then check the Included checkbox.

• Select all required Purpose Consents.

• Select the corresponding entries in the Vendor Consents, Vendors Allowed, and Vendors Disclosed tabs, ensuring RTB House S.A. (ID=16) is included along with your company. If necessary, locate your company's ID at https://www.uniconsent.com/tcf-decoder.

• Click Encode:

• Locate the generated string under the TCF String tab:

• Copy the encoded consent string and assign it to the gdpr_consent parameter in your URL.

RTB House Actions:

1. Confirm that the provided endpoint URL functions correctly.

2. Implement the URL as a dedicated endpoint and return this endpoint URL to the publisher. Incoming GDPR parameters and values are passed through without modification. The endpoint URL format is as follows:

   https://creativecdn.com/cm-notify?pi=<INTEGRATION_ID>&gdpr=1&gdpr_consent=&us_privacy=

   When accessed, this endpoint redirects to the publisher's endpoint URL while forwarding all corresponding GDPR parameter values.

Java Version

• Update src/main/resources/bidder-config/rtbhouse.yaml to the following (do not use the default file from the official Prebid Server repo):

  where an actual value in place of INTEGRATION_ID will be provided by RTB House.

  Please note that we do not support the {{redirect_url}} parameter within our cookie matching URL. This is why we provide the custom INTEGRATION_ID.

• When our cookie matching URL is invoked, it will redirect to the URL provided by the publisher with the dedicated parameter holding the current user's ID.

• In the app settings YAML file create custom publisher account for Prebid Server integration purposes with RTB House, eg.:

  You may choose the accounts.id value of your own. It's important to use this name consequently throughout the rest of this setup. This step is optional and you may mix other bidders using one single account. For testing purposes we suggest using a dedicated account though.

Go Version

• Create or update your pbs.yaml - the Prebid Server Go's runtime config file (or make appropriate changes to environment variables according to the PBS-Go documentation).

  Do not update the generic static/bidder-info/rtbhouse.yaml (the default file YAML file for rtbhouse bidder from the official Prebid Server repo).

  pbs.yaml:

  or environment variables:

  where an actual value in place of INTEGRATION_ID will be provided by RTB House.

  Please note that we do not support the {{.RedirectURL}} parameter within our cookie matching URL. This is why we provide the custom INTEGRATION_ID.

• When our cookie matching URL is invoked, it will redirect to the URL provided by the publisher with the dedicated parameter holding the current user's ID.

• In the app settings YAML file create custom publisher account for Prebid Server integration purposes with RTB House, eg.:

  You may choose the accounts.id value of your own. It's important to use this name consequently throughout the rest of this setup. This step is optional and you may mix other bidders using one single account. For testing purposes we suggest using a dedicated account though.

Client-side configuration

For detailed client-side Prebid.js configuration, please refer to https://inventoryguidelines.rtbhouse.com/prebid-integration/ This document contains only the additions specific to Prebid Server configuration.

prebid.js bundle file

• Make prebid.js bundle using the latest tagged version of Prebid.js with RTB House and Prebid Server adapters added:

Prebid config

• Update the publisher's prebid configuration script:

  • Add an additional bidder config object to the bids array (with bidder equal to rtbhouse) with the following obligatory parameters publisherId and region:

• Update the Prebid Server adapter configuration to include rtbhouse adapter:

  • If you're using the dedicated account please run

  • If you need to add the rtbhouse adapter to the list of adapters under an existing account:

Complete example

The following example runs a real Prebid Server communication (click Result tab to see the test page).
Please bear in mind that the example contains some hardcoded parameters that have to be changed to something realistic depending on your environment. Additionally, the server URL used is not intended for production usage.
There are hardcoded values for endpoint and syncEndpoint belonging to RTB House's Prebid Server endpoints, which you need to adjust.
You may also have to get rid of targetingControls config and probably you have to adjust to your adserver currency (the currency your line items are set at; see the currency object).
There's also a static GDPR config given (see the consentManagement object) which needs to be changed to 'iab' without the static GDPR parameters which were included here only for proper functioning in the testing sandbox.
See Prebid's documentation of how to use the GDPR Consent Management and GDPR Enforcement modules or refer to the Prebid.js integration page.

NOTICE: the userSync and consentManagement config objects are extremely important to RTB House's bidder and cookie sync endpoints. Cookies and GDPR must be properly configured in order to work correctly.

targetingControls is used here to only send hb_source KVP to the adserver. If you don't use it, you are free to get rid of it.

priceGranularity and currency configuration objects depend on the publisher's adserver Prebid line items setup.

Debugging

The below examples are real request payloads and their corresponding responses taken on a real web page which has the adserver currency set to EUR.
This is also an example of how currency conversion is taken in Prebid.js and Prebid Server. The setup follows the general rules as described on Prebid.js Currency Module documentation and Prebid Server Currency documentation.

Request/response without debug option

Example request

Notice the cur property set to ["EUR"].
Notice the site.publisher.id set to the value of s2sConfig.accountId which was given as one of the params to pbjs.setConfig which is also equal to the value given in app settings YAML file for Prebid Server (accounts.id).

Example response

Notice the cur property set to "EUR" The price seen in seatbid[].bid[].price is in the currency depicted in cur.
The RTB House bidder only accepts USD as currency so currency converter went into effect. This may be seen in seatbid[].bid[].ext.origbidcpm = 3.3875384654992757 and seatbid[].bid[].ext.origbidcur = "USD".
Another thing worth mentioning is that the targeting keys returned by the Prebid Server are ready to use by the client - they are already reconverted to EUR (compare "price": 3.197 and ext.prebid.targeting.hb_pb = "3.10" - rounding the price in EUR, not the price of USD 3.3875)

Request/response with debug option

Example request

Notice the ext.prebid.debug set to true.

Example response

Notice the ext.debug object containing the whole request in ext.debug.resolvedrequest (most of the data are copied from the original request) and the detailed S2S communication (request & response) between Prebid Server and the Bidder in ext.debug.httpcalls.rtbhouse[] object.
Details contain:

• uri - URL of the called bidder
• requestbody - stringified raw JSON object sent as payload from Prebid Server to Bidder
• responsebody - stringified raw JSON object sent as response from Bidder to Prebid Server
• requestheaders - full array of request headers sent in the S2S request
• status - HTTP status of the request

Details of S2S communication

Example request

The below example contains exactly what the above mentioned ext.debug.httpcalls.rtbhouse[].requestbody contains - it is only JSON-parsed.
Notice the user.buyeruid set to the exact same value as the cookie u set by the bidder's domain (creativecdn.com). This is the only place where you can see the cookie value as a plain text.
The cookie sent to the Prebid Server endpoint does not contain the Bidder's cookie - it may be totally in a different domain. It contains a obfuscated set of cookie values along with some other information (see detailed description here).
Notice that the currency here is already as USD as this is the direct request to the Bidder.

Example response

Similar as requestbody above, here comes the parsed ext.debug.httpcalls.rtbhouse[].responsebody
Notice the cur: "USD" as the Bidder responds only in USD

Professor Prebid

Professor Prebid is a powerful tool for debugging prebid & prebid server setup. You may get it as a Chrome extension: https://chrome.google.com/webstore/search/professor%20prebid

A brief manual: https://docs.prebid.org/tools/professor-prebid.html

A few screenshots taken on a real web page gazetkowo.pl with the Prebid Server setup according to the above rules and with Professor Prebid extension:

• 
• 
• 
• 
• 
•