Direct Server Side (S2S)

Introduction

Purpose

This specification is intended for Supply-Side platforms that want to integrate with Criteo and sell inventory. 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 whose source is liveramp.com (the RampID needs to be decrypted by the SSP using Sidecar)
The EIDS array contains a UID2.0 whose source is uidapi.com
The EIDS array contains a NetID whose source is netid.de
The EIDS array contains a SharedID whose source is sharedid.org
A Criteo RTUS ID is available and passed in user.ext.rtusid
An hashed email is available and includes the following based on 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 the 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

To invite Criteo to enter an auction, the partner will be provided with a set of URLs (“endpoints”), each of them pointing to a different Criteo data center. The general intent is that the data center closest to the user should be used; please contact Criteo for more details.

Only one bid request should be sent for a given auction, but multiple auction slots can be included within a bid request. The JSON file should have the structure below and top-level content.

Note:

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

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.
site	Object	Mandatory for Web	See Site object.
app	Object	Mandatory for In-App	See App object.
device	Object	Mandatory	See Device object.
user	Object	Mandatory	See User object.
at	Integer	Optional	Auction type, where 1 = First Price, 2 = Second Price Plus.
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. Criteo won't bid with an advertiser whose domain (or sub-domain) corresponds to an item of this block list. (ex: if `website.com` is in `badv`, then Criteo won't bid with neither `website.com` nor `awesome.website.com`)
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

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; Whenever an SSP also generates opportunities (through its own wrapper for example, or if it calls other SSPs, regardless of method), it needs to generate it. Whenever the SSP is downstream from a player that generates the `tid` (though PreBid.js for example, or Exchange bidding), the SSP should read it and transmit it to Criteo unaltered.
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
gpp	String	Recommended	Can also be sent as `regs.ext.gpp`. Protocol designed to streamline the transmission of privacy, consent, and consumer choice signals from sites and apps to ad tech providers. As of October 20th 2023, we support GDPR, TCFv2, CCPA and USNAT protocols from GPP.
gppsid	Object	Recommended	The section ID(s) (SID) in force for the current transaction. In most cases, this field should have a single section ID. In rare occasions where such a single section ID can not be determined, the field may contain up to 2 values, separated by a comma.

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).
gpid	String	Mandatory	A unique identifier for the placement of the ad that is the same for all SSPs. Criteo specific: Mandatory
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 (typically the tag provided by the SSP to the publisher). 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	Optional	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 - 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.3.
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.
skipmin	Integer	Optional	Videos of total duration greater than this number of seconds can be skippable; only applicable if the ad is skippable.
skipafter	Integer	Optional	Number of seconds a video must play before skipping is enabled; only applicable if the ad is 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. We support some of the elements listed in OpenRTB 2.6 version, like `2` (VPAID 2.0) and `7` (OMID 1.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
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 - Site Object

Field	Type	Status	Comment
id	String	Mandatory for exchange	Exchange-specific site ID.
domain	String	Recommended	The site's domain.
cat	String Array	Recommended	Array of IAB content categories of the site as described in OpenRTB 2.5
sectioncat	String Array	Recommended	Array of IAB content categories of the site as described in OpenRTB 2.5
pagecat	String Array	Recommended	Array of IAB content categories of the site as described in OpenRTB 2.5
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.
ref	String	Recommended	The referrer URL that caused navigation to the current page
search	String	Recommended	Search string that caused navigation to the current page
publisher	Object	Mandatory	See Publisher Object

Fields not supported:

Field	Comment
name	Not supported
mobile	Not supported
privacypolicy	Not supported
content	Not supported
keywords	Not supported
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.

Fields not supported:

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

Bid Request - 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.
name	String	Recommended	Name of the publisher
domain	String	Recommended	Highest-level domain of the publisher

Fields not supported:

Field	Comment
cat	Not supported
ext	Not supported

Bid Request - Device Object

Field	Type	Status	Comment
ua	String	Mandatory	The browser user agent string.
geo	Object	Mandatory	Criteo specific: mandatory to retrieve the user country. See geo object.
dnt	Integer	Mandatory	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.
lmt	Integer	Mandatory	The user’s expressed intent regarding ad tracking. Implemented depending on the operating system, should be 1 when limited ad tracking is required, 0 when it is not or the intent cannot be retrieved.
ip	String	Mandatory	The user's IP address.
os	String	Mandatory for In-App	The device OS: "iOS" for iOS, "Android" for Android.
language	String	Optional	The user’s browser language using ISO-639-1-alpha-2.
carrier	String	Recommended	Carrier or Internet Service Provider; similarly to OpenRTB 2.3, we do not offer an exhaustive list, but will be learning performance based on the content of the field.
connectiontype	Integer	Recommended	Network connection type (based on OpenRTB 2.3); we will be learning performance based on the content of the field.
ifa	String	Mandatory for inApp	The device’s advertising ID.

Fields not supported:

Field	Comment
ipv6	Not supported
devicetype	Not supported
make	Not supported
model	Not supported
osv	Not supported
hwv	Not supported
h	Not supported
w	Not supported
ppi	Not supported
pxratio	Not supported
js	Not supported
geofetch	Not supported
flashver	Not supported
mccmnc	Not supported
didsha1	Not supported
didmd5	Not supported
dpidsha1	Not supported by default, please contact your technical account manager to discuss potential integration
dpidmd5	Not supported by default, please contact your technical account manager to discuss potential integration
macsha1	Not supported
macmd5	Not supported
ext	Not supported

Bid Request - Geo Object

Field	Type	Status	Comment
country	String	Mandatory	Criteo specific: The user’s country at the time of the display, using ISO-3166-1-alpha-3.

Fields not supported:

Field	Comment
lat	Not supported
lon	Not supported
type	Not supported
accuracy	Not supported
lastfix	Not supported
ipservice	Not supported
region	Not supported
regionfips104	Not supported
metro	Not supported
city	Not supported
zip	Not supported
utcoffset	Not supported
ext	Not supported

Bid Request - User Object

Field	Type	Status	Comment
id	String	Recommended	The user's ID (SSP wide).
buyeruid	String	Mandatory for Web	The Criteo's user ID. See user matching section below for comments on how it is obtained.
yob	Integer	Optional	Year of birth as a 4-digit integer.
geo	Object	Recommended	See geo object.
consent	String	Recommended	Criteo specific: When the request is subject to GDPR regulations, this field is used to indicate the user's consent string. This can be also provided under `user.ext.consent`.
ext.eids	EID Array	Mandatory if existing	Contains the different IDs provided by the publishers or added on-the-fly by the SSP. More on this in the dedicated "User ID Collection" section

Fields not supported:

Field	Comment
gender	Not supported
keywords	Not supported
customdata	Not supported
data	Not supported

Bid Request - Skadn Object

Apple’s iOS 14 release changes how attribution is done across the mobile performance marketing landscape. An iOS user will have to provide consent in order for third-party companies to track their IDFA. SKAdNetwork is Apple’s solution to on-device attribution, which reduces the reliance on third party measurement partners. Criteo registered for SKAdNetwork with Apple and Criteo SKAdNetwork ID is : hs6bdukanm.skadnetwork

SKAdNetwork Support Flow (based on IAB)

SSP SDK retrieves the SKAdNetworkItems from the publisher app’s Info.plist
SDK makes ad request to ad server including SKAdNetworkItems
SSP determines from Info.plist which DSPs have SKAdNetwork capabilities. Bid request to eligible DSPs includes the imp.ext.skadn object, defined above
Criteo responds, including BidResponse.seatbid.bid.ext.skadn if the campaign requires SKAdNetwork support
Ad response to SDK includes skadn object
If the impression is shown and the user clicks, SSP calls loadProduct() with the appropriate data, including the Criteo-signed signature. If valid, Apple will consider the app for install attribution
Target app must register that user for SKAdNetwork attribution on app launch.
(Optional). Target app can choose to provide an additional 6 bits of conversion value information.
If SKAdNetwork determines that the DSP’s click led to the install, Apple will send a postback to the Criteo’s registered endpoint with the ids of the source app, target app and campaign, and conversion value if provided by the target app.

Field	Type	Status	Comment
version	String	Mandatory	Version of skadnetwork supported. Dependent on both the OS version and the SDK version.
sourceapp	String	Mandatory	ID of publisher app in Apple’s App Store. Should be equal to app.bundle value
skadnetids	String Array	Mandatory	A subset of SKAdNetworkItem entries in the publisher app’s Info.plist that are relevant to the DSP. Be aware that Criteo SKAdNetwork ID is : hs6bdukanm.skadnetwork

Bid Request - Bid Request Samples

Bid Response

Each bid response generated by Criteo is unique and must be used only once, in the same context as the original bid request. Criteo forbids the usage of bid-caching.

Bid Response - Response Top-Level Object

Field	Type	Comment
id	String	Criteo 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 Criteo will always return a single object inside it.
cur	String	The currency of the bid using ISO-4217 alphabetic codes.

Fields not supported:

Field	Comment
bidid	Not supported
customdata	Not supported
nbr	Not supported
ext	Not supported

Bid Response - Seatbid Object

Field	Type	Comment
bid	Object Array	See bid object. This is an array to accommodate OpenRTB and partner deserialization; in very rare cases Criteo will consider using multi-bids and leverage this structure.
seat	String	An identifier, commonly used to reflect Criteo’s billing requirement in the bidding process. Please refer to the billing section.

Fields not supported:

Field	Comment
group	Not supported
ext	Not supported

Bid Response - Bid Object

Bid being an array of objects, it explicitly allows for several bids to be present in the bid response. Though this will not be enabled in the general case, note that if several Criteo bids enter an auction, they cannot be used concurrently in the second-pricing mechanism.

Field	Type	Comment
id	String	Bidder generated bid ID to assist with logging/tracking.
impid	String	Criteo returns here the imp identifier passed in the bid request.
price	Float	Criteo’s bid in CPM value (1 means that Criteo is willing to pay 0.001 for this single impression).
nurl	String	Mandatory: contains the win notification url to be called when 'nurl' method is used. Please refer to the Notifications section for more information.
burl	String	Mandatory: contains the billing notification url to be called when 'burl' method is used. Please refer to the Notifications section for more information. This field is used for monitoring purposes, billing figures will still be based on creatives callouts via `adm` (or `eventtrackers` for native / `vast` for video).
lurl	String	Mandatory: contains the loss notification url to be called when 'lurl' method is used. Please refer to the Notifications section for more information.
adm	String	Criteo specific: only for Banner and Video inventories. 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. This macro will be sent for banner and video markups. Video adm will be an URL which will returns the video tag.
adm_native	Object	Criteo specific: only for Native inventory. Contains Native ad markup, see details below.
adid	String	ID of a preloaded ad to be served if the bid wins.
adomain	String Array	The domain of the advertiser Criteo is placing a bid for.
bundle	String	If applicable, a platform-specific application identifier intended to be unique to the app and independent of the exchange. On Android, this should be a bundle or package name (e.g., com.foo.mygame). On iOS, it is a numeric ID.
cid	String	Campaign ID to assist with ad quality checking.
crid	String	A unique identifier for the creative, internal to Criteo.
attr	Integer Array	Set of attributes describing the creative.
api	Integer	API required by the markup if applicable.
protocol	Integer	Video response protocol of the markup if applicable.
dealid	String	If present, it signals that Criteo wants the bid to be evaluated under the terms of the deal. It will only be used with a bidprice above the deal’s floorprice.
w	Integer	Banner and Video only, the width of the ad (to remove ambiguity when the Banner placement allowed for multiple sizes to compete).
h	Integer	Banner and Video only, the height of the ad (same as width above).
traceid	String	Criteo specific: A Criteo id used for debugging.
payload	String	Criteo specific: A unique string to be returned in the notification JSON under "payload" field; it can be up to 1024 characters long.
clickbrowser	Integer	Criteo specific: Indicates the type of browser which should be 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.
ext	Object	Placeholder for bidder-specific extensions to OpenRTB.

Fields not supported:

Field	Comment
iurl	URL without cache-busting to an image that is representative of the content of the campaign for ad quality/safety checking.
tactic	Not supported
cat	IAB content categories of the creative.
qagmediarating	Not supported
language	Not supported
wratio	Not supported
hratio	Not supported
exp	Not supported

Bid Response - Native ads (using Lazy Native mechanism)

For Native opportunities, Criteo will fill the adm field with adm_native.native.assetsurl per OpenRTB Native guidelines. This URL includes the price macro and should be triggered after the auction, if won by Criteo.

The rationale behind this implementation is the following:

Less timeouts, more spend: providing a creative requires us to identify the products for the creativeandload their assets at bid time. Avoiding this reduces Criteo’s computation time by half, decreasing our response times and timeouts.
Reduce the infrastructure footprint: this change will reduce the payload, which will lower the network time (and therefore the timeouts) as well as the use of bandwidth

Field	Type	Comment
link	Object	Contains landing URL for the click event
eventtrackers	Object array	Contains impression pixel URLs
assets	Object Array	List of Assets
assets[].img.ext.imagemode	Integer	Criteo specific: this field indicates the strategy the scaling strategy when rendering the product image (0: fit mode, 1: fill mode).
privacy	String	URL of a page informing the user about the buyer’s targeting activity.
ext.privacy	Privacy Object	Criteo specific: see Privacy Object below.
ext.demand	Demand Object	Criteo specific: see Demand Object below. Can be used to determine an ID for creative auditing purposes.

Bid Response - Privacy Object (Criteo specific)

Field	Type	Comment
imageurl	String	URL of the AdChoices icon.
clickurl	String	Link to the custom privacy page.
longlegaltext	String	Legal text mandatory in Russia.

Bid Response - Demand Object (Criteo specific)

Field	Type	Comment
productid	String	ID of the product
campaignid	Integer	ID of the campaign
advertiserid	Integer	ID of the advertiser

Bid Response - Skadn Object

Field	Type	Comment
version	String	Version of SKAdNetwork.
network	String	Ad network identifier used in signature.
campaign	String	Campaign ID compatible with Apple’s spec.
nonce	String	An id unique to each ad response.
sourceapp	String	ID of publisher’s app in Apple’s app store.
timestamp	String	Unix time in millis string used at the time of signature.
signature	String	SKAdNetwork signature as specified by Apple.

Bid Response - Bid Response Samples

User ID Collection

In order to enrich the bid request data with user IDs (1st Party user IDs, 3rd Party IDs or hashed emails), please use the forward the eids array as described in the sections below.

It corresponds to an array of OpenRTB EID objects as input:

Field	Type	Description
source	String	Identifier source URL (publisher URL or vendor URL).
uids[].id	String	User identifier
uids[].atype	Integer	Identifier type. `1`: an ID which is tied to a specific web browser or device (cookie-based, probabilistic, or other). `2`: in-app impressions, which will typically contain a type of device ID (or rather, the privacy-compliant versions of device IDs). `3`: a person-based ID, i.e., that is the same across devices.
uids[].ext.stype	String	ID Source type. `"dmp"` if comes from the in-page DMP named in eids.source. `"ppuid"` if comes from the publisher named in `eids.source`
uids[].ext.persistence	String	(Optional, Criteo-specific) In case of `uids[].ext.stype = "ppuid"`, corresponds to the way the ID is getting persisted. `"http"` if the ID was persisted through an HTTP Set-Cookie directive or `"js"` if the ID was set through JavaScript (either in a cookie or in the local storage).

User ID Collection - First Party IDs

Please make sure to follow the below specs (examples on the right):

source: the publisher's domain
id: the user identifier
atype: Must be 1 for cookie/device based ID, must be 3 for person-based ID (eg: authenticated user ID, login ID, CRM/customer ID)
ext.stype: ppuid
ext.persistence: js or http

User ID Collection - Third Party IDs

Please make sure to follow the below specs (examples on the right):

source: the third party solution domain
id: the user identifier
(recommended) atype: 1 for cookie/device based ID, 3 for person-based ID (eg: authenticated user ID, login ID, CRM/customer ID)
(optional) ext.persistence: js or http

User ID Collection - Hashed Emails

Please make sure to follow the below specs (examples on the right):

(optional) source: the publisher's domain or the domain of the solution operating on their behalf
id: the user data
atype: 3
ext.stype: hashing algorithm used: cleartextemail, hemsha256, hemmd5, hemsha256md5. Please refer to next section for details on hashing formats.

Hashing Formats

The hashing should be the users’ email address:

Encoded in UTF-8
Trimmed of any white space (eg: “test@criteo.com “ should become “test@criteo.com”)
Converted to lower case
Hashed with MD5/SHA256/SHA256(MD5) & output as ASCII text

Example:

Type: String
Original Email: john.doe@gmail.com
SHA256: 375320dd9ae7ed408002f3768e16cb5f28c861062fd50dff9a3bff62e9dce4ef
MD5: e13743a7f1db7f4246badd6fd6ff54ff
SHA256 of MD5: 000e3171a5110c35c69d060112bd0ba55d9631c7c2ec93f1840e4570095b263a

Helpful links : https://www.miraclesalad.com/webtools/md5.php and https://www.miraclesalad.com/webtools/sha256.php

Table of contents

Introduction

Purpose

Auction Definition

RTB Server-to-Server Protocol

Filtering

Bid Request

Bid Request - Request Top-Level Object

Bid request - Source Object

Bid Request - Regs Object

Bid Request - Imp 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 - Site Object

Bid Request - App Object

Bid Request - Publisher Object

Bid Request - Device Object

Bid Request - Geo Object

Bid Request - User Object

Bid Request - Skadn Object

Bid Request - Bid Request Samples

Bid Response

Bid Response - Response Top-Level Object

Bid Response - Seatbid Object

Bid Response - Bid Object

Bid Response - Native ads (using Lazy Native mechanism)

Bid Response - Privacy Object (Criteo specific)

Bid Response - Demand Object (Criteo specific)

Bid Response - Skadn Object

Bid Response - Bid Response Samples

User ID Collection

User ID Collection - First Party IDs

User ID Collection - Third Party IDs

User ID Collection - Hashed Emails

Hashing Formats