Skip to main content
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:

  1. A bid request is being sent to Criteo (among other buyers),

  2. Criteo has returned a bid response,

  3. The partner selecting a winner (if any),

  4. The partner allows the winner to display an ad to the user,

  5. 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 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 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 tid (though PreBid.js for example, or Exchange bidding), the partner 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

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 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

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 user.ext.consent.

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)

  1. Supply partner SDK retrieves the SKAdNetworkItems from the publisher app’s Info.plist

  2. SDK makes ad request to ad server including SKAdNetworkItems

  3. Supply partner determines from Info.plist which DSPs have SKAdNetwork capabilities. Bid request to eligible DSPs includes the imp.ext.skadn object, defined above

  4. Criteo responds, including BidResponse.seatbid.bid.ext.skadn if the campaign requires SKAdNetwork support

  5. Ad response to SDK includes skadn object

  6. 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

  7. Target app must register that user for SKAdNetwork attribution on app launch.

  8. (Optional). Target app can choose to provide an additional 6 bits of conversion value information.

  9. 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:

  1. 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.

  2. 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