Introduction
Welcome! This document will explain how to integrate with Criteo’s SSAI server-to-server solution.
Purpose
This specification is intended for Supply-Side platforms who want to integrate with Criteo and sell inventory. Complying with this specification, will allow for a faster and more efficient integration to Criteo’s production environment.
If you have any question 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 being sent to Criteo (among other buyers),
Criteo returning a bid response,
The partner selecting a winner (if any),
The partner allowing the winner to display an ad to the user,
The partner returning 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.
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.
User Sync
Please note that user sync can be set up by reaching out to your technical account manager.
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.buyeruidthe
EIDSarray contains an ID which source containscriteo(ex:criteo.com,esp.criteo.com)the
EIDSarray contains a RampID which source isliveramp.com(the RampID needs to be decrypted by the partner using Sidecar)the
EIDSarray contains a UID2.0 which source isuidapi.comthe
EIDSarray contains a NetID which source isnetid.dea Criteo RTUS ID is available and passed in
user.ext.rtusidan 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 followings:
"device.dnt" = 1
"device.lmt" = 1
"regs.coppa" = 1
Mobile-web interstitial
Please filter out traffic corresponding to the combination of the 3 followings:
Mobile (ex: "device.os" = "iOS" or "Android")
Web (ex: "site.page" exists)
Interstitial (ex: "instl" = 1)
Blocklisting API
Please filter out traffic which is linked to the list stored in 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 datacenter. The general intent is that the datacenter closest to the user should be used, please reach out to 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 positive impact on bidding pattern when implemented properly.
Optional fields have positive impact on operations and reporting.
Bid 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; Whenever a partner also generates opportunities (through its own wrapper for example, or if it calls other partners, regardless of method), it needs to generate it. Whenever the partner is downstream from a player that generates the |
pchain | String | Recommended | TAG payment ID chain string. |
ext.sourcetype | Integer | Mandatory | Criteo specific: Indicates the context of the bid request |
ext.sourceorigin | Integer | Mandatory | Criteo specific: Indicates the source of the request: Own tag on Page: 1, other partner: 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.
Please note that the imp.exp value is hardcoded to 3 hours.
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. |
video | Object | Mandatory for video | A Video object required. |
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 |
tagid | String | Mandatory | Unique identifier for the placement of the ad (typically the tag provided by the partner 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. |
Imp ext fields:
Field | Type | Status | Comment |
|---|---|---|---|
ext.bidder.uid | Integer | Optional | Custom optional parameter for Cgrid ad unit id, for cases where ad unit integration is needed |
Fileds not supported:
Field | Comment |
|---|---|
audio | Not supported |
secure | Criteo will always consider |
iframebuster | 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 - 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 - 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. |
at | Integer | Optional | Optional override of the overall auction type of the bid request, where 1 = First Price, 2 = Second Price Plus, 3 = the value passed in bidfloor is the agreed upon deal price. Additional auction types can be defined by the exchange. |
Fields not supported:
Field | Comment |
|---|---|
bidfloorcur | Deal currency must match the bid currency |
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. |
publisher | Object | Mandatory for exchange | See Publisher Object. |
paid | Integer | Optional | 0 = app is free, 1 = the app is a paid version. |
content | Object | Optional | See Content object. |
Fields not supported:
Field | Comment |
|---|---|
sectioncat | Not supported |
pagecat | Not supported |
ver | Not supported |
privacypolicy | Not supported |
keywords | Not supported |
ext | Not supported |
Bid Request - Content Object
Field | Type | Status | Comment |
|---|---|---|---|
title | String | Optional | Content title. |
series | String | Optional | Content series. |
genre | String | Optional | Genre that best describes the content (e.g., rock, pop, etc). |
producer | Object | Optional | Only support field producer.name (string). Content producer or originator name (e.g., “Warner Bros”). |
cat | String Array | Optional | Array of IAB content categories that describe the content producer. |
contentrating | String | Optional | Content rating (e.g., MPAA). |
userrating | String | Optional | User rating of the content (e.g., number of stars, likes, etc.). |
qagmediarating | Integer | Optional | Media rating per IQG guidelines. |
livestream | Integer | Optional | 0 = not live, 1 = content is live (e.g., stream, live blog). |
len | Integer | Optional | Length of content in seconds; appropriate for video or audio. |
language | String | Optional | Content language using ISO-639-1-alpha-2. |
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. Needs to be mapped on CGrid platform. |
name | String | Recommended | Name of the publisher |
domain | String | Recommended | Highest-level domain of the publisher |
Publisher.ext fields
Field | Type | Status | Comment |
|---|---|---|---|
ext.networkId | Integer | Mandatory | Mandatory publisher network Id to map the request to the proper account. Alternatively the ID can be passed via endpoint query param &networkid=. |
Fields not supported:
Field | Comment |
|---|---|
cat | 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; 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; 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 (partner 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 |
ext.eids | EID Array | Mandatory if existing | Contains the different IDs provided by the publishers or added on-the-fly by the partner. 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)
Partner SDK retrieves the SKAdNetworkItems from the publisher app’s Info.plist
SDK makes ad request to ad server including SKAdNetworkItems
Partner 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, partner 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 Samples
Bid Response
Each bid response generated by Criteo is unique and must be used only once, on the same context of the original bid request. Criteo forbids the usage of bid-caching.
Bid 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. |
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. |
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 |
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 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 video markups. Video adm will be an URL which will returns the video tag. |
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 | Video only, the width of the ad. |
h | Integer | Video only, the height of the ad. |
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. |
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 - Privacy Object (Criteo specific)
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. |