Table of contents
Introduction
Purpose
This specification is intended for supply partners who want to integrate server-to-server with Criteo’s Commerce Grid SSP following OpenRTB framework. 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 support-cgrid@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.
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).
User Sync
To implement redirect-based user sync, you should reach out to your technical account manager as we will need to authorize the domain called in the endpoint used for the callback.
The following endpoint can be used for redirect-based user sync
https://ssp-sync.criteo.com/user-sync/redirect?gdpr_consent=${GDPR_CONSENT}&gdpr=${GDPR}&gpp=${GPP}&gpp_sid=${GPP_SID}&redir=${CALLBACK}
You will need to replace the following macros with the proper user consent values:
Macro | Description |
|---|---|
${GDPR_CONSENT} | GDPR consent string |
${GDPR} | Whether GDPR regulations apply to this user or not. 0 = No, 1 = Yes |
${GPP} | Global Privacy Platform (GPP) string |
${GPP_SID} | Global Privacy Platform (GPP) section id |
${CALLBACK} | Callback function to call at the end of the redirect |
Note: the callback function provided should contain a macro ${CRITEO_USER_ID}.
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.
Mapping your inventory
You can map your inventory in one of 2 ways.
Option 1: Inventory groups mapping
If you don’t map your ad units, you can simply map your inventory groups. To do so, pass us the Publisher Id’s communicated by your Technical Account Manager via the app.publisher.id or site.publisher.id field.
Option 2: Ad units mapping
If you wish to map your ad units in Commerce Grid, your Technical Account Manager will share with you your Ad Unit Id's. You will have to pass them via the imp.ext.bidder.uid field.
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 |
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 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 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 |
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 |
tagid | String | Optional | Unique identifier for the placement of the ad. Meant as the most granular representation of a placement. Criteo specific |
bidfloor | Float | Optional | default 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.bidder.uid | String | Optional | The unique ID of the ad unit communicated by your Technical Account Manager to map them in Commerce Grid UI. |
ext | Object | Optional | Placeholder for exchange-specific extensions to OpenRTB. |
Fields not supported:
Field | Comment |
|---|---|
audio | Not supported |
secure | Criteo will always consider |
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 |
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 | Recommended | Whether your system/this impression supports returning an assetsurl instead of an asset object. 0 = assetsurl not supported, 1 = assetsurl supported in the bid response. Note: Commerce Grid may send a mix of responses containing assets or assetsurl in the response when aurlsupport = 1, as first-party demand from Criteo’s Commerce Growth DSP supports assetsurl but other DSPs may not support it. |
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 |
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 | Recommended | Your unique publisher ID communicated to you by your Technical Account Manager to map your inventory groups in Commerce Grid UI. |
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. |
ipv6 | String | Recommended | IP address closest to device as IPv6. |
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 |
|---|---|
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. |
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. 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)
Supply partner SDK retrieves the SKAdNetworkItems from the publisher app’s Info.plist
SDK makes ad request to ad server including SKAdNetworkItems
Supply 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, Supply 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 - 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 |
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. |