App S2S (OpenRTB)

Introduction

Welcome! This document will explain how to integrate with Criteo’s In-App server-to-server solution so you can begin your Criteo display campaign.

Purpose

This specification is intended for supply partners who want to integrate server-to-server with Criteo’s Commerce Grid SSP, e.g. server-side ad insertion (SSAI) vendors. Complying with this specification will allow for a faster and more efficient integration into Criteo’s production environment.

If you have any questions about this document, please reach out to rtbspecs@criteo.com.

Auction Definition

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

A bid request is being sent to Criteo (among other buyers),
Criteo has returned a bid response,
The partner selecting a winner (if any),
The partner allows the winner to display an ad to the user,
The partner returned feedback to Criteo.

Each of these steps will be specified in this document, along with parallel but equally important operations such as user matching and billing.

RTB Server-to-Server Protocol

Criteo uses JSON and the HTTP POST method.

Criteo returns HTTP 204 to signal that it doesn’t want to enter the auction.

Filtering

If you have the ability to do it, please filter out any traffic corresponding to the sections below.

User filtration

Unless instructed otherwise, Criteo should only receive bid requests containing an addressable ID from a Criteo perspective:

the user is matched with a Criteo UID provided in user.buyeruid
the EIDS array contains an ID which the source contains criteo (ex: criteo.com, esp.criteo.com)
the EIDS array contains a RampID which source is liveramp.com
the EIDS array contains a UID2.0 which source is uidapi.com
the EIDS array contains a NetID which source is netid.de
a Criteo RTUS ID is available and passed in user.ext.rtusid
an hashed email is available and included following these specs
an IFA is available (IDFA or GAID) and included in device.ifa

Privacy restrictions (DNT/LMT/COPPA)

Please filter out traffic corresponding to at least one of the following:

"device.dnt" = 1
"device.lmt" = 1
"regs.coppa" = 1

Mobile-web interstitial

Please filter out traffic corresponding to the combination of the 3 following:

Mobile (ex: "device.os" = "iOS" or "Android")
Web (ex: "site.page" exists)
Interstitial (ex: "instl" = 1)

(Native only) AdChoice icon handling

By default, please filter out Native traffic from publishers that can't handle the display of Criteo AdChoice icon (corresponding to the OpenRTB field. imp[i].native.privacy).

Blocklisting API

Please filter out traffic that is linked to the list stored in the blocklisting API. For more details, please refer to the Blocklisting API section.

Bid Request - 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.
imp	Object Array	Mandatory	See Imp object.
app	Object	Mandatory for In-App	See App object.
device	Object	Mandatory	See Device object.
user	Object	Mandatory	See User object.
tmax	Integer	Recommended	In milliseconds, the time after which bid responses will not enter the auction. Note that Criteo prefers no “throttling” mechanisms (reducing the volume of bid requests sent to relieve a host in case of timeouts) be used when timeouts occur. If they are enabled on your platform, please document them and share the documentation with your Criteo representatives.
wseat	String Array	Optional	Criteo specific: please contact your account manager if you need support on this field.
cur	String Array	Mandatory	Criteo specific: Mandatory. Array of allowed currencies for bids on this bid request using ISO-4217 alpha codes. The unique currency used by Criteo for all the slots contained in the bid requests will always be included in the bid response (CF "Response Top-Level Object" section below).
bcat	String Array	Optional	Blocked advertiser categories using the IAB content categories. If you want to use bcat, please contact us.
badv	String Array	Recommended	Block list of advertisers by their domains.
bapp	String Array	Recommended	Block list of advertisers by their bundle id.
source	Object	Mandatory	See Source object
regs	Object	Mandatory for EU users (Recommended otherwise)	See Regs object
at	Integer	Mandatory	Auction type, where 1 = First Price, 2 = Second Price Plus

Fields not supported:

Field	Comment
test	Not supported
bseat	Criteo is the only buyer
allimps	Not supported
wlang	Criteo relevant for Retargeting

Bid Request - Source Object

Field	Type	Status	Comment
fd	Integer	Mandatory	Entity responsible for the final impression sale decision, 0 = exchange / 1 = upstream source
tid	String	Mandatory	Unique identifier for the impression generated by whoever originates the impression
pchain	String	Recommended	TAG payment ID chain string.
ext.sourcetype	Integer	Mandatory	Criteo specific: Indicates the context of the bid request `1` if the request doesn't come from a header-bidding context, `2` if the request comes from a client-side header bidding auction, `3` if the request comes from a server-side header bidding auction
ext.sourceorigin	Integer	Mandatory	Criteo specific: Indicates the source of the request: Own tag on Page: 1, other SSP: 2, Amazon TAM: 3, EBDA: 4, Prebid: 5, Index HB: 6, Other HB solution: 7
ext.schain	Object	Mandatory	Enable buyers to see all parties who are selling or reselling a given bid request. More information can be found here.

Bid Request - 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)	Criteo specific: Flag indicating if this request is subject to the GDPR regulations, where 0 = no, 1 = yes. This can be also provided as a Regs extension object.
us_privacy	String	Mandatory for Californian citizens	Criteo specific: 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', '-'. More information can be found here

Bid Request - Imp Object

Imp must describe separate opportunities to show an ad. In other words, it must be possible to display as many ads as there are elements on the imps array .

Criteo supports three types of impressions: Banners, Native Image and Video. For information, we don't support Native Video yet.

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).
metric	Object Array	Recommended	See Metric object.
banner	Object	Mandatory for banner	A Banner object required if this impression is offered as a banner ad opportunity.
video	Object	Mandatory for video	A Video object required if this impression is offered as a banner ad opportunity.
native	Object	Mandatory for native	A Native object required if this impression is offered as a banner ad opportunity.
pmp	Object	Optional	See PMP object. This details whether the ad opportunity is eligible to multiple deals with different terms.
displaymanager	String	Mandatory for App and Video	Criteo specific: Name of ad mediation partner, SDK technology, or player responsible for rendering ad. Criteo specific
displaymanagerver	String	Mandatory for App and Video	Criteo specific: version of the display manager
instl	Integer	Mandatory	Set to `1` when the impression is destined to be an interstitial or full-page. Criteo specific
tagid	String	Mandatory	Unique identifier for the placement of the ad. Meant as the most granular representation of a placement. Criteo specific
bidfloor	Float	Mandatory	Criteo specific: Mandatory, default to 0. The minimum amount for which the impression can be sold, expressed in the currency set in the Request Top-Level Object.
bidfloorcur	String	Optional	Currency specified using ISO-4217 alpha codes. This may be different from bid currency returned by bidder if this is allowed by the exchange.
clickbrowser	Integer	Mandatory for App	Indicates the type of browser opened upon clicking the creative in an app, where 0 = embedded, 1 = native. Note that the Safari View Controller in iOS 9.x devices is considered a native browser for purposes of this attribute. Criteo specific: mandatory for app
ext	Object	Mandatory	Placeholder for exchange-specific extensions to OpenRTB.

Fields not supported:

Field	Comment
audio	Not supported
secure	Criteo will always consider `secure = 1`
iframebuster	Not supported
exp	Not supported

Bid Request - Ext Object

Field	Type	Status	Comment
zoneid	Integer	Mandatory	The Criteo zone ID, an unique identifier for the placement (typically a number).

Bid Request - Metric Object

Field	Type	Status	Comment
type	String	Mandatory	Type of metric being presented using exchange. Eg: "viewability"
value	Float	Mandatory	The value, from 0.0 to 1.0
vendor	String	Mandatory	Source of the value. Eg: "moat.com"

Fields not supported:

Field	Comment
ext	Not supported

Bid Request - Banner Object

Field	Type	Status	Comment
format	Object Array	Mandatory	Criteo specific: 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). Sizes must be provided via Format object, even if there's only a single size possible
w	Integer	Mandatory	Criteo specific: Mandatory. Width of first sizes in the Format array. Required as it's used to determine if a Banner opportunity is present in the bid request. If you can't support this field, please contact your account manager for potential alternatives.
h	Integer	Mandatory	Criteo specific: Mandatory. Height of first sizes in the Format array. Required as it's used to determine if a Banner opportunity is present in the bid request. If you can't support this field, please contact your account manager for potential alternatives.
battr	Integer array	Recommended	Blocked creatives attributes. Refer to list 5.4.
pos	Integer	Recommended	Follows the Ad Position IAB standard for Above-The-Fold, Below-The-Fold, etc. Refer to List 5.4.
topframe	Integer	Recommended	Indicates if the banner is in the top frame as opposed to an iframe, where 0 = no, 1 = yes.
expdir	Integer array	Optional	Directions in which the banner may expand. Refer to List 5.5.
api	Integer array	Recommended	List of supported API frameworks for this impression as described in OpenRTB 2.5, List 5.6

Fields not supported:

Field	Comment
wmax	Not supported
hmax	Not supported
wmin	Not supported
hmin	Not supported
btype	Not applicable for Criteo
mimes	Not applicable for Criteo
ext	Not supported

Note:

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 sizes object 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 impressions object should be present, with two sizes objects in the array.

Bid Request - Video Object

Field	Type	Status	Comment
mimes	String Array	Mandatory	Content MIME types supported (e.g., “video/x-ms-wmv”,“video/mp4”)
minduration	Integer	Mandatory	Minimum video ad duration in seconds.
maxduration	Integer	Mandatory	Maximum video ad duration in seconds.
protocols	Integer Array	Mandatory	Array of supported video protocols. Refer to list 5.8
w	Integer	Mandatory	Width in pixels
h	Integer	Mandatory	Height in pixels
startdelay	Integer	Recommended	Indicates the start delay in seconds for pre-roll, mid-roll, or post-roll ad placements.
placement	Integer	Mandatory	Placement type for the impression. Refer to List 5.9
linearity	Integer	Recommended	1 = Linear, 2 = Non-linear.
skip	Integer	Mandatory	0 = Not skippable, 1 = Skippable.
playbackmethod	String Array	Mandatory	Playback method that may be in use. Only first element of Array will be used
api	Integer Array	Mandatory	List of supported API frameworks for this impression. 1 = VPAID 1.0, 2 = VPAID 2.0.
ext.rewarded	Integer	Recommended	Criteo specific: 1 if rewarded video type, 0 otherwise. This field can be provided on the video extension object

Fields not supported:

Field	Comment
protocol	Not supported
skipmin	Not supported
skipafter	Not supported
sequence	Not supported
battr	Not supported
maxextended	Not supported
minbitrate	Not supported
maxbitrate	Not supported
boxingallowed	Not supported
playbackend	Not supported
delivery	Not supported
pos	Not supported
companionad	Not supported
companiontype	Not supported

Bid Request - Native Object

Criteo Native integration relies on OpenRTB Native Specs 1.2 (https://iabtechlab.com/wp-content/uploads/2016/07/OpenRTB-Native-Ads-Specification-Final-1.2.pdf)

In order to decrease timeout, Criteo chose to adopt AssetsURL, where the assets responses are retrieved post-auction.

Please notice that this slightly differs from the original OpenRTB approach as this call provides extra information besides the assets. See the Native Bid Response section for more details.

The Native request object is described as below.

Field	Type	Status	Comment
ver	String	Recommended	Version
context	Integer	Recommended	The context in which the ad appears.
contextsubtype	Integer	Recommended	The sub-context in which the ad appears
plcmttype	Integer	Recommended	The design/format/layout of the ad unit being offered.
plcmtcnt	Integer	Recommended	The number of identical placements in this Layout
assets	Object Array	Mandatory	Array of assets objects.
aurlsupport	Integer	Mandatory	Criteo specific: must be 1. Criteo expects all native requests to support Criteo assetsurl mode on the bid response.
privacy	Integer	Mandatory	Criteo specific: must be 1. Indicates that the native ad supports buyer-specific privacy notice. If it causes an issue, please contact your account manager to discuss potential alternatives.
ext	Object	Optional	Reserved for exchange-specific extensions.

Fields not supported:

Field	Comment
seq	Not supported
durlsupport	Not supported
eventtrackers	Not supported
battr	Not in the OpenRTB Native 1.2 specs
api	Not in the OpenRTB Native 1.2 specs

Bid Request - Format Object

Field	Type	Status	Comment
w	Integer	Mandatory	Criteo specific Width in pixels of a supported size.
h	Integer	Mandatory	Criteo specific Height in pixels of the same supported size.

Fields not supported:

Field	Comment
wratio	Not supported
hratio	Not supported
wmin	Not supported
ext	Not supported

Bid Request - PMP Object

Field	Type	Status	Comment
private_auction	Integer	Mandatory for deals	Indicator of auction eligibility to seats named in the Direct Deals object, where 0 = all bids are accepted, 1 = bids are restricted to the deals specified and the terms thereof.
deals	Object array	Mandatory for deals	Array of Deal (see below) objects that convey the specific deals applicable to this impression

Fields not supported:

Field	Comment
ext	Not supported

Bid Request - Deal Object

Note:

They must be explicitly approved by Criteo, either via a UI or an email, before being present in a bid request.
Criteo will then return the deal ID in the bid response when it wants the bid to be evaluated under the terms of the deal.
If Criteo doesn’t want to leverage the terms of the deal, the bid (which will not contain the deal ID and can be of any value) must remain eligible to win the auction.

Field	Type	Status	Comment
id	String	Mandatory	A unique identifier for the deal.
bidfloor	Float	Mandatory	The minimum amount for a bid to be part of the deal, expressed in the currency set in the auction object.

Fields not supported:

Field	Comment
bidfloorcur	Deal currency must match the bid currency
at	Expected to be the same as the top-level request
wseat	Criteo is the only buyer
wadomain	Criteo is the only buyer
ext	Not supported

Bid Request - App Object

Field	Type	Status	Comment
id	String	Mandatory for exchange	Exchange-specific app ID.
name	String	Recommended	The application’s name; null when unknown.
bundle	String	Mandatory	Application bundle or package name (e.g. "com.foo.mygame" on Android and numeric on iOS). This is intended to be a unique ID across multiple exchanges.
domain	String	Recommended	Application domain (e.g. "mysupergame.com").
storeurl	String	Recommended	Application store URL (e.g. iTunes store URL or Android store URL).
cat	String Array	Recommended	Array of IAB content categories of the site/page as described in OpenRTB 2.5
publisher	Object	Mandatory for exchange	See Publisher Object.
content	Object	Optional	Supported for passing contextual taxonomy data. See RTD documentation for more details

Fields not supported:

Field	Comment
sectioncat	Not supported
pagecat	Not supported
ver	Not supported
privacypolicy	Not supported
paid	Not supported
keywords	Not supported
ext	Not supported

Table of contents

Introduction

Purpose

Auction Definition

RTB Server-to-Server Protocol

Filtering

Bid Request - Request Top-Level Object

Bid Request - Source Object

Bid Request - Regs Object

Bid Request - Imp Object

Bid Request - Ext Object

Bid Request - Metric Object

Bid Request - Banner Object

Bid Request - Video Object

Bid Request - Native Object

Bid Request - Format Object

Bid Request - PMP Object

Bid Request - Deal Object

Bid Request - App Object