RTB Buy Documentation
Table of Contents
Introduction
This document provides instructions on how to access SourceKnowledge's Domain Targeting Network through Real-Time Bidding.
Please note, as the bidder, you are responsible for providing the RTB endpoint. You will find examples to help guide you below.
By moving forward with this integration, the bidder is agreeing to the following conditions:
Final billing numbers are recorded by SourceKnowledge - a dashboard login will be provided for tracking.
The bidder is responsible for paying for every click they bid on and win.
The bidder's endpoint should respond to at least 10% of total requests.
- The domain provided in the response must always match the ad destination.
Terminology
The following terms are used throughout this document
| Term | Definition |
|---|---|
| RTB | Bidding for individual clicks in real-time (i.e., while a consumer is waiting). |
| Publisher | An entity that operates one or more sites. |
| Exchange | A service that conducts an auction among bidders per click. |
| Bidder | An entity that competes in real-time auctions to acquire clicks. |
| Site | Ad supported content including websites and apps. |
Data Format
JSON (JavaScript Object Notation) is the suggested format for bid request and bid response data payloads. JSON is the industry standard and was chosen for its combination of human readability and compactness.
The bid request specifies the representation as a mime type using the Content-Type HTTP header. The mime type for the standard JSON representation is "application/json" as shown. The format of the bid response must be the same as the bid request.
Content-Type: application/json
Request
The following are all the macros that SourceKnowledge is able to send with each bid request.
Macros:
| Macros | Required? | Description |
|---|---|---|
destDomain | Required | The target destination domain. We currently do not support keywords. |
| bidfloor | Required | Minimum bid for this request. You must bid at or above the bid floor provided to win the auction. |
| device.ip | Recommended | The user’s IP address |
| device.ua | Recommended | The user’s User Agent String (url-encoded) |
| device.geo.country | Recommended | The user’s geography |
| sub_id | Recommended | Partner-defined subid for internal reporting |
| ext.bidid | Optional | Unique click identifier |
| oadest | Optional | Destination Url (can be used for Deep Linking) |
| traffic_type | Optional | Numeric id representing Type of Traffic. (See below table for detail) |
| tmax | Optional | The amount of time in milliseconds before the auction times out or closes. |
| top_bid | Optional | Top Bid |
The parameter names are customizable and chosen by you. To ensure accurate data processing, append our macro after your desired parameter.
Traffic Type Classification:
| ID | Classification |
|---|---|
| 1 | PLA |
| 2 | Social |
| 3 | Deal Site |
| 4 | Ad Network |
| 5 | Apps & Plugins |
| 6 | Intext |
| 7 | Other |
| 8 | Domain Redirect |
| 9 | BNPL |
| 10 | Push |
| 11 | Native |
| 12 | Blog |
| 13 | Newsletter |
For a description of each Traffic Type, please visit the Help Center.
Request Format
The feed is queried by making a request to a constructed URL containing at least the required parameters:
https://feed.example.com/endpoint?key=99999&bidid={bidid}&ip={ip}&ua={ua}&domain={domain}&subid={subid}&bidfloor={bidfloor}&url={dest}&traffic_type={traffic_type}&top_bid={top_bid}
https://feed.example.com/endpoint?key=99999&bidid=1000000112&ip=23.85.65.74&ua=Mozilla%2F5.0%20(X11%3B%20Linux%20x 86_64)%20AppleWebKit%2F537.36%20(KHTML%2C%20like%20Gecko)%20Chrome%2F37.0.2062.94%20S afari%2F537.36&domain=wayfair.com&subid=sf84292412b289&bidfloor=0.25&top_bid=1.25&url=https%3A%2F%2Fwww.wayfair.com%2Ffurniture%2Fpdp%2Fsteelside-myra-desk-w004812250.html
In the above example, SourceKnowledge will be calling your endpoint passing the required parameters, giving you the option to bid.
Response
RTB responses contain bids that reference specific clicks within a bid request. Bids are in essence an offer to buy. An empty HTTP response constitutes a no-bid and is in fact the most bandwidth friendly form of this signal although returning a response with a "no-bid reason" is encouraged. A malformed response or a response that contains no actual bids will also be interpreted as no-bid.
Calls returning content, such as a bid response, should return HTTP code 200. Calls returning no content in response to valid requests (e.g., an empty bid response which is one option for indicating no-bid) should return HTTP 204. Invalid calls (e.g., a bid request containing a malformed or corrupt payload) should return HTTP 400 with no content.
The response time should stay around 100ms.
| Parameters | Description |
|---|---|
| url | The click url the user should be redirected to |
| bid | The "net" bid amount the advertiser will pay for a successful click of the url in US dollars. (USD) |
| adid | The creative id for the returned ad. |
| uuid | A unique identifier for the bid. This could also be called a 'clickid' |
{
"url": "https://tracking.example.com/click?x=abc1234",
"bid": "0.45750",
"adid": "2399",
"uuid": "1234567890abcdef"
}
In the above example, you will be returning the following to SourceKnowledge. If you are the highest bidder, your provided click url will be used.