This specification is intended for Supply-Side platforms who want to integrate with E- Planning to sell their inventory. Complying with this specification will allow for a faster and more efficient integration to E-Planning’s production environment.
Contents
| Table of Contents | ||||
|---|---|---|---|---|
|
Auction
What is often referred to as an “auction” consists of:
A bid request being sent to E-Planning (among other buyers)
E-Planning returning a bid response
The partner selecting a winner (if any)
The partner allowing the winner to display an ad to the user
Each of these steps will be specified in this document, along with parallel but equally important operations such as user matching.
RTB Server-to-Server Protocol
E-Planning uses JSON and the HTTP POST method.
E-Planning returns HTTP 204 to signal that it does not want to enter the auction.
The E-Planning RTB protocol and spec was built upon OpenRTB 2.3. However, some OpenRTB 2.5 features are supported (like Banner.format).
Bid Request
To invite E-Planning to enter an auction, the partner will be provided with a set of URLs (“endpoints”), each of them pointing to a different E-Planning data center. The general intent is that the data center closest to the partner’s data center should be used. Please reach out to your E-Planning technical contact for more details.
Only one bid request should be sent for a given auction, but multiple impression slots of the same can and should be included within a single bid request. The JSON file should have the structure below.
| Info | ||
|---|---|---|
| ||
|
Request Top-Level Object
...
An identifier for the request, it can be used to connect the bid request to the bid response outside of the HTTP protocol
...
In milliseconds, the time after which bid responses will not enter the auction
...
Auction type, where 1 = First Price, 2 = Second Price Plus
...
See Imp object
...
Flag to indicate whether all the impressions of the context are available or not
...
See User object
...
See Site object
...
See Regs object
...
Block list of advertisers by their domains
...
Blocked advertiser categories using the IAB content categories
Example
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
{
"id": "bfebe4d6f24efacd",
"tmax": 300,
"at": 1,
"cur": ["USD"],
"imp": [{ "...": "..." }],
"user": { "...": "..." },
"device": { "...": "..." },
"site": { "...": "..." },
"source": { "...": "..." },
"regs": { "...": "..." },
"badv": ["ford.com","bmw.com"],
"bcat":, ["IAB8-1","IAB8-2"]
} |
Imp Object
...
A unique identifier for this impression within the context of the bid request (typically, starts with 1 and increments)
...
A Banner object
...
Currency in which the bid response is expected, including the floor prices. using ISO-4217 alpha codes. Example: "USD"
...
The minimum amount for which the impression can be sold, expressed in the currency set in bidfloorcur
...
Set to1 if the snipped in the bid response must use HTTPS
...
Set to 1 when the impression is destined to be an interstitial or full- page
...
Example
This specification is intended for Supply-Side platforms who want to integrate with E-Planning to sell their inventory. Complying with this specification will allow for a faster and more efficient integration to E-Planning’s production environment.
Contents
| Table of Contents | ||||
|---|---|---|---|---|
|
Auction
What is often referred to as an “auction” consists of:
A bid request being sent to E-Planning (among other buyers)
E-Planning returning a bid response
The partner selecting a winner (if any)
The partner allowing the winner to display an ad to the user
Each of these steps will be specified in this document, along with parallel but equally important operations such as user matching.
RTB Server-to-Server Protocol
E-Planning uses JSON and the HTTP POST method.
E-Planning returns HTTP 204 to signal that it does not want to enter the auction.
The E-Planning RTB protocol and spec was built upon OpenRTB 2.3. However, some OpenRTB 2.5 features are supported (like Banner.format).
Bid Request
To invite E-Planning to enter an auction, the partner will be provided with a set of URLs (“endpoints”), each of them pointing to a different E-Planning data center. The general intent is that the data center closest to the partner’s data center should be used. Please reach out to your E-Planning technical contact for more details.
Only one bid request should be sent for a given auction, but multiple impression slots of the same can and should be included within a single bid request. The JSON file should have the structure below.
| Info | ||
|---|---|---|
| ||
|
Request Top-Level Object
| Field | Type | Status | Comment |
|---|---|---|---|
| id | String | Mandatory | An identifier for the request, it can be used to connect the bid request to the bid response outside of the HTTP protocol |
| tmax | Integer | Recommended | In milliseconds, the time after which bid responses will not enter the auction |
| at | Integer | Mandatory | Auction type, where 1 = First Price, 2 = Second Price Plus |
| imp | Object Array | Mandatory | See Imp object |
| allimps | Integer | Recommended | Flag to indicate whether all the impressions of the context are available or not |
| user | Object | Mandatory | See User object |
| device | Object | Mandatory | See Device object |
| site | Object | Mandatory for Web | See Site object |
| app | Object | Mandatory for In-App | See App object |
| source | Object | Mandatory | See Source object |
| regs | Object | Mandatory | See Regs object |
| badv | String Array | Recommended | Block list of advertisers by their domains |
| bcat | String Array | Recommended | Blocked advertiser categories using the IAB content categories |
Example
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
{
"id": "bfebe4d6f24efacd",
"tmax": 300,
"at": 1,
"cur": ["USD"],
"imp": [{ "...": "..." }],
"user": { "...": "..." },
"device": { "...": "..." },
"site": { "...": "..." },
"source": { "...": "..." },
"regs": { "...": "..." },
"badv": ["ford.com","bmw.com"],
"bcat":, ["IAB8-1","IAB8-2"]
} |
Imp Object
| Field | Type | Status | Comment |
|---|---|---|---|
| id | String | Mandatory | A unique identifier for this impression within the context of the bid request (typically, starts with 1 and increments) |
| banner | Object | Mandatory for display | A Banner object |
| video | Object | Mandatory for video | A Video object |
| bidfloorcur | String | Mandatory | Currency in which the bid response is expected, including the floor prices. using ISO-4217 alpha codes. Example: "USD" |
| bidfloor | Float | Mandatory | The minimum amount for which the impression can be sold, expressed in the currency set in bidfloorcur |
| secure | Integer | Mandatory | Set to1 if the snipped in the bid response must use HTTPS |
| instl | Integer | Recommended | Set to 1 when the impression is destined to be an interstitial or full- page |
| clickbrowser | Integer | Mandatory for In-App | Indicates the type of browser which should be opened upon clicking the creative in an app, where 0 = embedded, 1 = native |
Example
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
{
"id": "1",
"bidfloor": 0.4286,
"bidfloorcur": "USD",
"secure": 1,
"instl": 0,
"banner": {
"w": 300,
"h": 250,
"pos": 1,
"topframe": 0
},
"tagid": "79a4e192e54cc0d9"
} |
Banner Object
| Field | Type | Status | Comment |
|---|---|---|---|
| format | Object Array | Mandatory if “w” and “h” are not set | See Format Object. Formats allowed in the auction; it is an array to reflect the fact that many publisher placements support several sizes considered as part of one auction (e.g. 300x250 or 300x600). |
| w | Integer | Mandatory if “format” is not set | Width in pixels of the banner supported size |
| h | Integer | Mandatory if “format” is not set | Height in pixels of the banner supported size |
| wmin | Integer | Recommended if “format” is not set | Minimum width in pixels of the banner supported size |
| wmax | Integer | Recommended if “format” is not set | Maximum width in pixels of the banner supported size |
| hmin | Integer | Recommended if “format” is not set | Minimum height in pixels of the banner supported size |
| hmax | Integer | Recommended if “format” is not set | Maximum height in pixels of the banner supported size |
| pos | Integer | Recommended | Follows the Ad Position IAB standard for Above-The-Fold, Below-The-Fold, etc. |
| topframe | Integer | Recommended | Indicates if the banner is in the top frame as opposed to an iframe, where 0 = no, 1 = yes |
| api | Integer | Recommended | List of supported API frameworks for this impression as described in OpenRTB 2.5. If you are sending inApp traffic, please consider add OMID-1 flag (7) if is supported. |
| battr | Integer Array | Recommended | Blocked creatives attributes |
| btype | Integer Array | Recommended | Blocked banner ad types |
| expdir | Integer Array | Optional | Directions in which the banner may expand |
| Info | ||
|---|---|---|
| ||
|
Example
Using format
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
{
"idpos": "1",
"bidfloorformat": 0.4286,
"bidfloorcur": "USD",
"secure": 1,
"instl": 0,
"banner": {
"w": 300,
"h": 250,
"pos": 1[
{
"w": 300,
"topframeh": 0600
},
"tagid": "79a4e192e54cc0d9"
} |
Banner Object
...
Mandatory if “w” and “h” are not set
...
See Format Object. Formats allowed in the auction; it is an array to reflect the fact that many publisher placements support several sizes considered as part of one auction (e.g. 300x250 or 300x600).
...
Mandatory if “format” is not set
...
Width in pixels of the banner supported size
...
Mandatory if “format” is not set
...
Height in pixels of the banner supported size
...
Recommended if “format” is not set
...
Minimum width in pixels of the banner supported size
...
Maximum width in pixels of the banner supported size
...
Minimum height in pixels of the banner supported size
...
Maximum height in pixels of the banner supported size
...
Follows the Ad Position IAB standard for Above-The-Fold, Below-The-Fold, etc.
...
Indicates if the banner is in the top frame as opposed to an iframe, where 0 = no, 1 = yes
...
List of supported API frameworks for this impression as described in OpenRTB 2.5. If you are sending inApp traffic, please consider add OMID-1 flag (7) if is supported.
...
Blocked creatives attributes
...
Blocked banner ad types
...
Directions in which the banner may expand
| Info | ||
|---|---|---|
| ||
|
Example
Using format
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
{
"pos": 1,
"format": [
{
"w": 300,
"h": 600
},
{
"w": 300,
"h": 250
}
],
"battr": [ 11, 12 ],
"btype": [ 4 ]
} |
Using w and h
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
{ "pos": 1, "w": 300, "h": 250, "wmin": 300, "wmax": 300, "hmin": 50, "hmax": 600, "battr": [ 11, 12 ], "btype": [ 4 ] } { "w": 300, "h": 250 } ], "battr": [ 11, 12 ], "btype": [ 4 ] } |
Using w and h
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
{
"pos": 1,
"w": 300,
"h": 250,
"wmin": 300,
"wmax": 300,
"hmin": 50,
"hmax": 600,
"battr": [ 11, 12 ],
"btype": [ 4 ]
} |
Video Object
| Field | Type | Status | Comment |
|---|---|---|---|
| w | Integer | Mandatory | The width of the player, in pixels |
| h | Integer | Mandatory | The height of the player, in pixels |
| maxduration | Integer | Mandatory | Maximum video ad duration, in seconds |
| minduration | Integer | Mandatory | Minimum video ad duration, in seconds |
| mimes | String Array | Mandatory | A list of supported video content MIME types. Popular MIME types supported by HTML5 players include: video/mp4, video/webm, video/ogg. For VPAID support, make sure to specify application/javascript. |
| protocols | Integer Array | Mandatory | An array of supported video protocols. At least one supported protocol must be specified, where: 2 = VAST 2.0, 3 = VAST 3.0, 5 = VAST 2.0 Wrapper, 6 = VAST 3.0 Wrapper |
| pos | Integer | Recommended | Follows the Ad Position IAB standard for Above-The-Fold, Below-The-Fold, etc. |
| api | Integer | Recommended | List of supported API frameworks for this impression as described in OpenRTB 2.5. If you are sending inApp traffic, please consider add OMID-1 flag (7) if is supported. |
| battr | Integer Array | Recommended | Blocked creatives attributes |
| boxingallowed | Integer | Recommended | Specifies whether letter-boxing of 4:3 content into a 16:9 window is allowed, where: 0 = boxing is not allowed, 1 = boxing is allowed (default setting) |
| delivery | Integer Array | Optional | A list of supported delivery methods. If blank, it is assumed that all are supported, where: 1 = streaming, 2 = progressive |
| linearity | Integer Array | Optional | Specifies whether the ad impression is linear or non-linear. If the field is blank, the ad impression can be of any type, where: 1 = linear/in stream, 2 = non-linear/overlay |
Format Object
| Field | Type | Status | Comment |
|---|---|---|---|
| w | Integer | Mandatory | Width in pixels of a supported size |
| h | Integer | Mandatory | Height in pixels of the same supported size |
...
| Field | Type | Status | Comment |
|---|---|---|---|
| id | String | Mandatory | Exchange-specific site ID |
| page | String | Mandatory | The URL of the page on which the impression will be shown; field should be absent when unknown or alternatively an empty string |
| publisher | Object | Mandatory | See Publisher Object |
| domain | String | Recommended | The domain of the page |
| cat | String Array | Recommended | Array of IAB content categories of the site as described in OpenRTB 2.5. Max 8 categories. |
| ref | String | Recommended | The referrer URL that caused navigation to the current page |
| ext.inventorypartnerdomain | String | Recommended | Inventory partner domain. Third-party domain authorized to validate ads.txt |
Example
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
{
"id": "123",
"page": "http://example.com/section/page.html",
"cat": [ "IAB1-2" ],
"publisher": {
"id": "456",
"domain": "example.com",
"name": "Example Inc"
}
} |
App Object
| Field | Type | Status | Comment |
|---|---|---|---|
| id | String | Obligatorio | Exchange-specific app ID |
| name | String | Obligatorio | The application’s name |
| bundle | String | Obligatorio | Application bundle or package name (e.g. "com.foo.mygame" on Android and numeric on iOS) |
| domain | String | Recomendado | Application domain |
| storeurl | String | Recomendado | Application store URL (e.g. iTunes store URL or Android store URL) |
| cat | String Array | Recomendado | Array of IAB content categories of the site as described in |
| OpenRTB 2.5. Max 8 categories. | |||
| ext.inventorypartnerdomain | String | Recommended | Inventory partner domain. Third-party domain authorized to validate app-ads.txt |
Example
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
{
"id": "12345",
"name": "My App",
"bundle": "com.foo.myapp",
"domain": "myapp.com",
"storeurl": "https://store.com/app/12345",
"cat": [ "IAB1-2" ],
"publisher": {
"id": "456",
"domain": "example.com",
"name": "Example Inc"
}
} |
...
| Field | Type | Comment |
|---|---|---|
| id | String | Bidder generated bid ID to assist with logging/tracking. |
| impid | String | E-Planning returns here the imp identifier passed in the bid request. |
| price | Float | E-Planning’s bid in CPM value (1 means that E- Planning is willing to pay 0.001 for this single impression). |
| adm | String | The creative ad markup to pass to the browser if the bid wins the auction; the markup includes a macro that must be replaced by the partner with the price it will be charged, in CPM value. |
| adomain | String Array | The domain of the advertiser E-Planning is placing a bid for. |
| w | Integer | The width of the ad (to remove ambiguity when the placement allowed for multiple sizes to compete). |
| h | Integer | The height of the ad (to remove ambiguity when the placement allowed for multiple sizes to compete). |
| lurl | String | Loss notice URL called by the exchange when a bid is known to have been lost. ${AUCTION_PRICE} and ${AUCTION_LOSS} macros are included. Exchange-specific policy may preclude support for loss notices or the disclosure of winning clearing prices resulting in macros being removed (i.e., replaced with a zero-length string). |
| Info | ||
|---|---|---|
| ||
E-Planning counts the impression via creative code on adm, in consequence nurl is not supported. |
...
E-Planning provides partner with a sync URL, which partner should fire from traffic using an IFRAME tag. After URL is called from user's browser E-Planning will handle user's cookies on its side. Then E-Planning will redirect the user to a redirect URL which SSP provides to E- Planning.
There is a placeholder in this redirect URL, which E-Planning will replace with buyeruid generated on our side. This process only applies to Web auctions, not being necessary in In-App.
Example of supply partner’s redirect URL: http://test-partner-domain.com/?uid=$UID, E-Planning will replace $UID placeholder with some buyeruid (e.g. “e3cf38b549b50e01”) and redirect user using this URL.
Partner shall pass a redirect URL as "redir" parameter in E-Planning sync URL:
https://ads.us.e-planning.net/uspd/1/<CLIENT_ID>?ruidm=1&du=<ENCODED_REDIRECT_URL>
Note <CLIENT_ID> is provided by E-Planning
Here is the example of final sync IFRAME tag:
| Code Block | ||
|---|---|---|
| ||
<iframe src="https://ads.us.e-planning.net/uspd/1/5a1ad71d2d53a0f5?ruidm=1&du=https%3A%2F%2Ftest-partner-domain.com%2F%3Fuid%3D%24UID" width="0" height="0" style="display: none;"></iframe> |
It will redirect to:
https://test-partner-domain.com/?uid=e3cf38b549b50e01
buyeruid format
E-Planning’s buyeruid is a fixed 16 characters length string in all cases, eg: "e3cf38b549b50e01"
Compression
E-Planning can receive compressed bid requests from partners and send them back compressed bid responses. E-Planning recommends usage of compression in requests and responses to decrease auction latency and save network bandwith.
...