Overview

This guide is for Equativ’s demand partners and explains how to use the OpenRTB API, including setup, configuration as well as the supported objects and parameters.

Equativ is compliant with the OpenRTB 2.2, 2.3, 2.4 and 2.5 specifications. OpenRTB 2.4 or 2.5 with banner.format objects is the preferred implementation and other versions are supported only for legacy connections. For Native Ads, Equativ follows OpenRTB Native Ads API Specification Version 1.0 and 1.2. OpenRTB and the Native Ads API are published by the IAB and may be downloaded here. Topics such as SSAI, CTV and rewarded placements are standardized and to be implemented as per OpenRTB 2.6.

The integration process

To ensure a smooth integration, please review this document, inform Equativ of any known limitations or incompatibilities, and provide Equativ with a test URL that complies with this specification.

Equativ will then start integrating your bidding platform, and check multiple aspects, for example, ad display, win notice, and counting. Once one or more endpoint URLs have been provided, the integration team will proceed as follows:

1. Manual testing on simple requests to check that platform responses are compatible. For this step, Equativ requires Equativ's partners:
   1. to have a test ad campaign available to respond to Equativ's test calls and,
   2. if required by the buyer, to provide Equativ with a valid User ID to be sent in the test request to return an ad.
2. Activation on some limited live traffic to compare impressions and media spend numbers to check for discrepancies and confirm platform stability in live conditions
   1. tests usually last for a couple of hours at a time agreed upon by Equativ and the partner,
   2. campaigns targeted to be delivered on at least part of the test traffic must be activated,
   3. after the campaign ends, Equativ will send impressions and media spend measured and expect similar numbers in return.
3. If number comparison is satisfying, the partner will be activated on Equativ traffic.

RTB Integration

Protocol

Equativ sends bid requests across the HTTP protocol. Bid requests are sent in a POST request using JSON serialization with no encryption. Requests use the following headers:     x-openrtb-version: 2.x         2.x being one of current versions supported: 2.3, 2.4, 2.5, etc. as per integration     Expect: 100-continue (only on request and if proved useful via testing) Http request timeout: 100ms. Regular bids must return HTTP code 200. Empty bids (‘no-bid’) must return one of the following as per IAB:

• HTTP code 204 and no content.
• HTTP code 200 and an empty JSON object: {}
• HTTP code 200 and a well formed no bid response: {"id":"1234567890", "seatbid":[]}
• HTTP code 200 and a well formed no bid response with reason code: {"id":"1234567890", "seatbid":[], "nbr ":2}

Compression

GZip is supported:

• For bid requests on activation as part of integration.
• For bid responses as indicated for each auction by the Accept-Encoding header in transmitted requests.

Data Centers

Equativ is currently present in:

• EMEA:
  • 3 data centers near Paris, France.
  • 1 data center in Amsterdam, the Netherlands
  • 1 data center in Gravelines, France
• US-East:
  • 1 data center in Vint Hill, Virginia, USA
  • 1 data center in Washington DC, USA
• US-West: 1 data center in Los Angeles, California, USA to service traffic and publishers from the Americas/West.
• APAC: 1 data center in Singapore, Singapore

You can call the following URLs to measure round-trip time for the following data centers:

• Paris:
  • EQX: https://eqx-secure.smartadserver.com/r20-dyn.gif
  • ITX5: https://itx5-secure.smartadserver.com/r20-dyn.gif
  • ITX4: https://itx4-secure.smartadserver.com/r20-dyn.gif
• EU-West:
  • EUW1: https://euw1-secure.smartadserver.com/r20-dyn.gif
  • EUW2: https://euw2-secure.smartadserver.com/r20-dyn.gif
• US-East: TMK: https://tmk-secure.smartadserver.com/r20-dyn.gif
• US-West USW1: https://usw1-secure.smartadserver.com/r20-dyn.gif
• Singapore: APAC1: https://apac1-secure.smartadserver.com/r20-dyn.gif

Endpoint Monitoring

Each data center probes its connected (live) production demand endpoints periodically with non-billable requests to check endpoint availability. These requests are indicated as non-billable test requests by setting the OpenRTB standard bidrequest.test flag to 1. A standard no-bid response is expected on these requests and errors or timeouts detected on these requests or on production traffic will automatically disable the endpoint until valid responses have been re-established from the endpoint.

Example request

{
	"id": "261026854545260597",
	"imp": [{
			"id": "8e9843b8-ed10-44e9-a5bd-83e9c80d289d",
			"banner": {
				"w": 300,
				"h": 250,
				"mimes": ["text/html"]
			},
			"tagid": "MCAw"
		}
	],
	"site": {
		"id": "234563",
		"name": "Smart RTB+ Monitoring",
		"domain": "rtbmonitoring.smartadserver.com",
		"page": "http://rtbmonitoring.smartadserver.com/page.htm",
		"publisher": {
			"id": "73",
			"name": "Smart RTB+ Monitoring"
		}
	},
	"device": {
		"ua": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/61.0.3163.100 Safari/537.36",
		"ip": "185.86.136.0",
		"geo": {
			"country": "FRA"
		}
	},
	"user": {
		"id": "0"
	},
	"at": 2,
	"cur": ["EUR"],
	"test": 1
}

Partner Endpoint URL

You can provide Equativ with either:

• One global URL to send BidRequests to from any location by Equativ, leaving geo-balancing to be done on your end.
• Multiple endpoint URLs to be called by Equativ depending on the data center handling the bid.

Keep Connections Alive

Equativ recommends using “keepalive” connections and setting the idle time up to 2 minutes to reuse the connections as many times as possible. Doing so will minimize latency, use fewer resources, and decrease the likelihood of a timeout.

Supported Display Scenarios

Equativ supports the following scenarios:

• In-Browser banners for both mobile and desktop devices.
• In-App banners for Android & iOS Mobile devices.

Note: The only content type accepted in banner.adm is "text/html". Other types will not execute in Equativ's banner placements. JavaScript must be properly embedded in <script> tags, for example, as adm is injected directly into the placement.

Macros & Encryption

Supported Macros

Currently only in win notification, burl and adMarkup.

Win-Price Encryption

On request, the auction price macro value contained in the AdMarkup can be encrypted following the private data communication protocol. Equativ provides the required keys on demand. For example, the demand partner returns:

“[your ad tag]
<img height=’1’ width=’1’ src=’http://www.yourdomain/winnotification/pixel/${AUCTION_PRICE}’ />”
Equativ will deliver
“[your ad tag]
<img height=’1’ width=’1’ src=’http://www.yourdomain/winnotification/pixel/2b30CPRaSbCDzbM5ZrfSx2k-ZZ7qcHmZMdlevA’ />”

You will be able to decrypt the price with the provided keys. Bidding and Billing Currency The following currencies may be declared and used within Equativ:

• Euro (EUR)
• US Dollar (USD)
• Polish Zloty (PLN)

Other currencies will be handled upon request. This currency will be used both in BidRequest/BidResponse according to OpenRTB specification and in Billing sent by Equativ to the partner.

Billing Timezone

Billing will be handled on a monthly basis on any timezone of partner’s choosing.

Deals and Private Marketplace

Multi Seat Support

For deal/private marketplace functionality and partners wishing to be able to send multiple SeatBids in a BidResponse, Equativ will require a list of existing seats with the following structure: - SeatId : Id of the seat - SeatName: Name of the seat / buyer

Programmatic Guaranteed

A Guaranteed deal is a fixed volume deal with one or more buyers for a specific inventory and/or audience. The buyer(s) involved get(s) the first look at impressions eligible to the deal and thus have priority to buy them at the fixed deal price. Programmatic Guaranteed deals are indicated with the following extension and value in the deal object:

"ext":{
    "smart":{
        "guaranteed": 1
    }
}

"guaranteed": 1 indicates a guaranteed deal and a value of 0 for this field or the lack of this field indicates the deal is not operating under a Programmatic Guaranteed context.