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

Auction

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

1. A bid request being sent to E-Planning (among other buyers)

2. E-Planning returning a bid response

3. The partner selecting a winner (if any)

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

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

{
	"id": "bfebe4d6f24efacd",
	"tmax": 300,
	"at": 1,
	"cur": ["USD"],
	"imp": [{ "...": "..." }],
	"user": { "...": "..." },
	"device": { "...": "..." },
	"site": { "...": "..." },
	"source": { "...": "..." },
	"regs": { "...": "..." },
	"badv": ["ford.com","bmw.com"],
	"bcat":, ["IAB8-1","IAB8-2"]
}

...

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

Auction

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

1. A bid request being sent to E-Planning (among other buyers)

2. E-Planning returning a bid response

3. The partner selecting a winner (if any)

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

Request Top-Level Object

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

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

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

Format Object

Site Object

Example

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

App Object

Example

{
	"id": "112345",
	"bidfloorname": 0.4286 "My App",
	"bidfloorcurbundle": "USDcom.foo.myapp",
	"securedomain": 1"myapp.com",
	"instlstoreurl": 0"https://store.com/app/12345",
	"bannercat": {[ 		"wIAB1-2": 300],
		"hpublisher": 250,{
		"posid": 1"456",
		"topframedomain": 0"example.com",
	},
	"tagidname": "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

...

Blocked creatives attributes

...

Blocked banner ad types

...

Directions in which the banner may expand

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 ]
}

Format Object

...

Width in pixels of a supported size

...

Height in pixels of the same supported size

Site Object

Example Inc"
	}
}

Publisher Object

Example

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

Content Object

This object describes the content in which the impression will appear, which may be syndicated or non-syndicated content. This object may be useful when syndicated content contains impressions and does not necessarily match the publisher’s general content. This object is highly recommended in CTV inventory and should be sent whenever possible.

Producer Object

This object defines the producer of the content in which the ad will be shown. This is particularly useful when the content is syndicated and may be distributed through different publishers and thus when the producer and publisher are not necessarily the same entity.

Example

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

...

Channel Object

This object describes the channel an ad will be displayed on. A Channel is defined as the entity that curates a content library, or stream within a brand name for viewers. Examples are specific view selectable ‘channels’ within linear and streaming television (MTV, HGTV, CNN, BBC One, etc) or a specific stream of audio content commonly called ‘stations.’ Name is a human-readable field while domain and id can be used for reporting and targeting purposes.

Example

...

...

User Object

Example

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

Device Object

Example

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

Example

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

Regs Object

Example

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

Example

Using pchain

{
	"fd": 1,
	"pchain": "directseller.com:12345"
}

...

Response Top-Level Object

Seatbid Object

Bid Object

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

...

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:

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

...