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.

1 Auction
2 RTB Server-to-Server Protocol
3 Bid Request
- 3.1 Request Top-Level Object
- 3.2 Imp Object
- 3.3 Banner Object
- 3.4 Video Object
- 3.5 Format Object
- 3.6 Site Object
- 3.7 App Object
- 3.8 Publisher Object
- 3.9 Content Object
- 3.10 Producer Object
- 3.11 Channel Object
- 3.12 User Object
- 3.13 Device Object
- 3.14 Geo Object
- 3.15 Regs Object
- 3.16 Source Object
- 3.17 Bid Request example
4 Bid Response
- 4.1 Response Top-Level Object
- 4.2 Seatbid Object
- 4.3 Bid Object
- 4.4 Bid Response example
5 Auction pricing macros
6 User Matching
- 6.1 buyeruid format
7 Compression
8 Persistent connections

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.

Note

Mandatory fields must be included.
Recommended fields have positive impact on bidding pattern when implemented properly.
Optional fields have positive impact on operations and reporting.

Request Top-Level Object

Field	Type	Status	Comment

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

{
	"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

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

{
	"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

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

Note

Both OpenRTB 2.3 and 2.5 size formats are supported. We strongly recommend to not set both at the same time, but if you do, OpenRTB 2.5 format will be discarded.
- OpenRTB 2.3: Is "w" and "h"
- OpenRTB 2.5: Is "format"
If the intent is to sell two placements on a single page, for example a 728x90 “leaderboard” at the top of the page and a 300x250 rectangle on the right-hand side of the page, two impressions objects should be present with a single size object in each
If the intent is to sell a single placement that can host either a 300x250 rectangle creative or a 300x600 “half-page” creative, then only one impression object should be present, with two size objects in the array

Example

Using format

{
	"pos": 1,
	"format": [
		{
			"w": 300,
			"h": 600
		},
		{
			"w": 300,
			"h": 250
		}
	],
	"battr": [ 11, 12 ],
	"btype": [ 4 ]
}

Using w and h

{
	"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

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

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

Site Object

Field	Type	Status	Comment

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

{
	"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

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)

OpenRTB connection

Contents

Auction

RTB Server-to-Server Protocol

Bid Request

Request Top-Level Object

Example

Imp Object

Example

Banner Object

Example

Using format

Using w and h

Video Object

Format Object

Site Object

Example

App Object