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.

Table of Contents

maxLevel	3
exclude	ContenidoContents\|EjemploExample

Auction

What is often referred to as an “auction” consists of:

...

Info

title	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
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	See Site 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

language	js
linenumbers	true
collapse	true

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

Example

Code Block

language	js
linenumbers	true
collapse	true

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

title	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

...

Code Block

language	js
linenumbers	true
collapse	true

{
	"pos": 1,
	"w": 300,
	"h": 250,
	"wmin": 300,
	"wmax": 300,
	"hmin": 50,
	"hmax": 600,
	"battr": [ 11, 12 ],
	"btype": [ 4 ]
}

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

Site Object

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
ref	String	Recommended	The referrer URL that caused navigation to the current page

Example

Code Block

language	js
linenumbers	true
collapse	true

{
	"id": "123",
	"page": "http://example.com/section/page.html",
	"cat": [ "IAB1-2" ],
	"publisher": {
		"id": "456",
		"domain": "example.com",
		"name": "Example Inc"
	}
}

Publisher Object

Field	Type	Status	Comment
id	String	Mandatory	The publisher’s unique ID; it should be sufficient to identify the party ultimately being paid for the impression auctioned. Cannot be null
domain	String	Recommended	Highest-level domain of the publisher
name	String	Recommended	Name of the publisher

Example

Code Block

language	js
linenumbers	true
collapse	true

{
	"id": "456",
	"domain": "example.com",
	"name": "Example Inc"
}

User Object

Field	Type	Status	Comment
id	String	Recommended	The user’s ID (SSP wide)
buyeruid	String	Recommended	The E-Planning’s user ID. See user matching section below for comments on how it is obtained

Example

Code Block

language	js
linenumbers	true
collapse	true

{
	"id": "1234567",
	"buyeruid": "e3cf38b549b50e01",
	"consent": "BOEFEAyOEFEAyAHABDENAI4AAAB9vABAASA"
}

Device Object

Field	Type	Status	Comment
ua	String	Mandatory	The browser user agent string
ip	String	Mandatory	The user's IP address
dnt	Integer	Recommended	The user’s intent regarding tracking. If a dnt value was sent in the header by the client application when calling the partner, the value 1 should be passed in this field; if no value was sent, it should be 0.
language	String	Optional	The user’s browser language using ISO- 639-1-alpha-2
carrier	String	Recommended	Carrier or Internet Service Provider
connectiontype	Integer	Recommended	Network connection type
os	String	Recommended	The device OS
geo	Object	Recommended	See the Geo Object

Example

Code Block

language	js
linenumbers	true
collapse	true

{
	"ip": "142.93.199.194",
	"ua": "Mozilla\/5.0 (Macintosh; Intel Mac OS X 10.12; rv:71.0) Gecko\/20100101 Firefox\/71.0",
	"os": "macOS",
	"carrier": "verizon",
	"connectiontype": 6,
	"dnt": 0,
	"geo": {
		"country": "USA",
		"city": "Stanford"
	}
}

Geo Object

Field	Type	Status	Comment
country	String	Mandatory	The user's country at the time of the display, using ISO- 3166-1-alpha-3
city	String	Recommended	The user's city
latitude	Float	Recommended	Latitude from -90.0 to +90.0, where negative is south
longitude	Float	Recommended	Longitude from - 180.0 to +180.0, where negative is west

Example

Code Block

language	js
linenumbers	true
collapse	true

{
	"latitude": 37.4194,
	"longitude": -122.164,
	"country": "USA",
	"city": "Stanford"
}

Regs Object

Field	Type	Status	Comment
coppa	Integer	Recommended	Flag indicating if this request is subject to COPPA regulations, where 0 = no, 1 = yes
gdpr	Integer	Mandatory for EU users (Recommended otherwise)	Flag indicating if this request is subject to the GDPR regulations, where 0 = no, 1 = yes
ext.consent	String	Recommended	When the request is subject to GDPR regulations, this field is used to indicate the user's consent string
us_privacy	String	Recommended	Flag indicating is this request is subject to the CCPA (California Consumer Privacy Act) regulations. CCPA field should be exactly 4 chars length, with first char must be 1 (correspond to version), the 3 remaining chars must be either 'Y' or 'y', 'N or 'n', '-'. https://iabtechlab.com/wp-content/uploads/2019/11/U.S.-Privacy-String-v1.0-IAB-Tech-Lab.pdf

Example

Code Block

language	js
linenumbers	true
collapse	true

{
	"gdpr": 1,
	"coppa": 1,
	"us_privacy": "1-N-",
	"ext": {
		"consent": "BOq9e8JOq9e8lAHABBESCv- AAAAst7_______9______9uz_Ov_v_f__33e8__9v_l_7_-___u_-3zd4u_1vf99yfm1-7etr3tp_87ues2_Xur__79__3z3_9pxP78k89r7337Ew_v-_v8b7BCIJ"
	}
}

Source Object

Field	Type	Status	Comment
fd	Integer	Mandatory	Entity responsible for the final impression sale decision, 0 = exchange / 1 = upstream source
pchain	String	Recommended if "schain" is not set	TAG payment ID chain string
ext.schain	String	Recommended if "pchain" is not set	Per IAB's supply chain object proposal

Info

title	Note

For pchain implementation we accept both TAG ID or domain identification

...

Response Top-Level Object

Field	Type	Comment
id	String	E-Planning returns here the identifier present in the corresponding bid request; this is not necessary for the protocol but allows to match the request and response outside of the HTTP bidding protocol.
seatbid	Object Array	See seatbid object. This is an array to accommodate OpenRTB and partner deserialization, but E-Planning will always return a single object inside it.
cur	String	The currency of the bid using ISO-4217 alphabetic codes.

Seatbid Object

Field	Type	Comment
seat	String	An identifier, commonly used to reflect E-Planning’s billing requirement in the bidding process.
bid	Object Array	See Bid object

Bid Object

Bid being an array of objects, it explicitly allows for several bids to be present in the bid response.

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).

Info

title	Note

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.

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

language	xml

<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.

...

Version	Old Version 1	New Version 2
Changes made by	Sebastian Perez (Unlicensed)	Sebastian Perez (Unlicensed)
Saved on	Jul 27, 2020	Jul 27, 2020

Versions Compared

Key

Auction

Request Top-Level Object

Example

Imp Object

Example

Banner Object

Format Object

Site Object

Example

Publisher Object

Example

User Object

Example

Device Object

Example

Geo Object

Example

Regs Object

Example

Source Object

Response Top-Level Object

Seatbid Object

Bid Object

buyeruid format

Compression

Content Comparison

Versions Compared

Key

Auction

Request Top-Level Object

Example

Imp Object

Example

Banner Object

Format Object

Site Object

Example

Publisher Object

Example

User Object

Example

Device Object

Example

Geo Object

Example

Regs Object

Example

Source Object

Response Top-Level Object

Seatbid Object

Bid Object

buyeruid format

Compression