Table of contents
Introduction
Welcome! This document will explain how to integrate with Criteo’s In-App server-to-server solution so you can begin your Criteo display campaign.
Purpose
This specification is intended for in-app publishers 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.
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. The Criteo RTB protocol and spec was built prior to the emergence of OpenRTB as a standard. Whenever possible, Criteo moved closer to the OpenRTB guidelines and will continue to do so while preserving backward compatibility. Criteo complies with IAB Consent Framework. See User Object section for details.
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 auctions can be included within a bid request (see section 2.1.7 below). 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 - Request Top-Level Object
Field | Type | Status | Comment |
---|---|---|---|
requestid | 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. |
auction | Object | Mandatory | See auction object. |
impressions | Object Array | Mandatory | See impressions object. |
user | Object | Mandatory | See user object. |
device | Object | Mandatory | See device object. |
publisher | Object | Mandatory | See publisher object. |
app | Object | Mandatory for In-App | See app object. |
site | Object | Mandatory for Web | See site object. |
badv | String Array | Recommended | Block list of advertisers by their domains. |
bcat | String Array | Optional | Blocked advertiser categories using the IAB content categories. If you want to use bcat, please contact us. |
Bid Request - Auction Object
Field | Type | Status | Comment |
---|---|---|---|
id | String | Optional | An identifier for the auction that will be held; mostly used for debugging and troubleshooting. |
timeout | 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. |
currency | String | Recommended | The currency in which the bid response is expected, represented using ISO-4217 alpha codes. Can be defined outside of the communication protocol. |
Bid Request - User Object
Field | Type | Status | Comment |
---|---|---|---|
id | String | Recommended | The user's ID (SSP wide). |
buyeruid | String | Recommended | The Criteo's user ID. See user matching section below for comments on how it is obtained. |
useragent | String | Recommended | The user agent passed by the client application when calling the partner. |
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. |
coppa | Integer | Mandatory | Flag indicating if this request is subject to COPPA regulations, where 0 = no, 1 = yes. |
country | String | Optional | The user’s country at the time of the display, using ISO-3166-1-alpha-3. |
language | String | Optional | The user’s browser language using ISO-639-1-alpha-2. |
geo | Object | Recommended | See geo object. |
yob | Integer | Optional | Year of birth as a 4-digit integer. |
gdpr | Integer | Recommended | Flag indicating if this request is subject to the GDPR regulations, where 0 = no, 1 = yes. |
us_privacy | String | Recommended | 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', '-'. https://iabtechlab.com/wp-content/uploads/2019/11/U.S.-Privacy-String-v1.0-IAB-Tech-Lab.pdf |
consent | String | Recommended | When the request is subject to GDPR regulations, this field is used to indicate the user's IAB consent string. |
ext.eids | EID Array | Mandatory if existing | Contains the different IDs provided by the publisher. More on this in the dedicated “User ID Collection” section |
Bid Request - Geo Object
Field | Type | Status | Comment |
---|---|---|---|
latitude | Float | Recommended | Latitude from -90.0 to +90.0, where negative is south. |
longitude | Float | Recommended | Longitude from -180.0 to +180.0, where negative is west. |
Bid Request - Device Object
Field | Type | Status | Comment |
---|---|---|---|
id | String | Mandatory for inApp | The device’s advertising ID. |
ip | String | Mandatory | The user's IP address. |
category | String | Mandatory for In-App | The device ID’s category; can be “IDFA” for iOS, “GAID” for the Android advertising ID. Please contact us if you support additional categories such as SHA1 Device IDs, etc. |
system | String | Mandatory | The device’s operating system; similarly to OpenRTB 2.4, we do not offer an exhaustive list, but will be learning performance based on the content of the field. |
environment | String | Mandatory | Must be "web" or "inapp". |
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. |
lmt | Integer | Recommended for In-App | 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. |
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. |
domain | String | Recommended | Highest-level domain of the publisher |
Bid Request - App Object
Field | Type | Status | Comment |
---|---|---|---|
id | String | Recommended | 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"). 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). |
Bid Request - Site Object
Field | Type | Status | Comment |
---|---|---|---|
id | String | Mandatory | Exchange-specific site ID. |
page | String | Mandatory | The URL of the page on which the impression will be shown; field should be absent of JSON when unknown or alternatively an empty string. |
domain | String | Recommended | The site's domain. |
Bid Request - Impressions Object
Impressions must describe separate opportunities to show an ad. In other words, it must be possible to display as many ads as there are impressions.
Criteo supports two types of impressions: Banner and Native. Criteo doesn't support Video.
Field | Type | Status | Banner | Native | Comment |
---|---|---|---|---|---|
id | String | Mandatory | x | x | A unique identifier for this impression within the context of the bid request (typically, starts with 1 and increments). |
zoneid | String | Mandatory | x | x | The Criteo zone ID, an unique identifier for the placement (typically a number). |
tid | String | Mandatory | x | x | Unique identifier for the impression generated by whoever originates the impression; Whenever an SSP also generates opportunities (through its own wrapper for example, or if it calls other SSPs, regardless of method), it needs to generate it. Whenever the SSP is downstream from a player that generates the |
tagid | String | Mandatory | x | x | Unique identifier for the placement of the ad (typically the tag provided by the SSP to the publisher). Meant as the most granular representation of a placement. |
sourcetype | Integer | Mandatory | x | x | Indicates the context of the bid request |
creativetype | String | Mandatory | x | x | Creative type of the impression. Could be |
displaytype | String | Optional | x | Indicates the type of invocation code supported; must be either “Iframe” or “Javascript”. | |
displaymanager | String | Recommended | x | x | Name of ad mediation partner, SDK technology, or player responsible for rendering ad (typically mobile). |
displaymanagerver | String | Recommended | x | x | Version of ad mediation partner, SDK technology, or player responsible for rendering ad (typically mobile). |
instl | Integer | Mandatory | x | x | Set to |
secure | Integer | Mandatory | x | x | Set to |
visibility | Integer | Recommended | x | x | Follows the Ad Position IAB standard for Above-The-Fold, Below-The-Fold, etc. |
viewability | Integer | Recommended | x | x | Viewability of the ad placement, when a view is defined as 50% of the placement staying in the browser’s viewport more than 1 seconds; expressed as a 0-100 value where 100 means that the placement is fully viewed. |
api | Integer Array | Recommended | x | x | List of supported API frameworks for this impression as described in OpenRTB 2.5 |
floorprice | Float | Mandatory | x | x | The minimum amount for which the impression can be sold, expressed in the currency set in the auction object. |
sizes | Object Array | Mandatory for Banner | x | See size object. Sizes 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). | |
deals | Object Array | Optional | x | x | See deal object. This is an array to reflect that an impression may be eligible to multiple deals with different terms. |
clickbrowser | Integer | Mandatory for App | x | Criteo specific: 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. |
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 - Size Object
Field | Type | Status | Comment |
---|---|---|---|
w | Integer | Mandatory | Width in pixels of a supported size. |
h | Integer | Mandatory | Height in pixels of the same supported size. |
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. |
floorprice | Float | Mandatory | The minimum amount for a bid to be part of the deal, expressed in the currency set in the auction object. |
Bid Request - Bid Request Samples
Bid Response - Response Top-Level Object
Field | Type | Comment |
---|---|---|
requestid | 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. |
Bid Response - Seatbid Object
Field | Type | Comment |
---|---|---|
seat | String | An identifier, commonly used to reflect Criteo’s billing requirement in the bidding process. Please refer to the billing section. |
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. |
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 | Banner | Native | Comment |
---|---|---|---|---|
impid | String | x | x | Criteo returns here the identifier passed in the bid request. |
traceid | String | x | x | A Criteo id used for debugging. |
lurl | String | x | x | An optional field that contains the loss notification url to be called when 'nurl' method is used. Please refer to bid loss notifications section for more information. |
bidprice | Float | x | x | Criteo’s bid in CPM value (1 means that Criteo is willing to pay 0.001 for this single impression). |
currency | String | x | x | The currency of the bid using ISO-4217 alphabetic codes. |
dealid | String | x | x | 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. |
adomain | String | x | x | The domain of the advertiser Criteo is placing a bid for. |
crid | String | x | x | A unique identifier for the creative, internal to Criteo. |
fillimages | Integer | x | A flag that tells if the image should be in fill or fit mode by the publisher render. 1= fill / 0= fit | |
adm | String | x | 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 markup. | |
w | Integer | x | The width of the ad (to remove ambiguity when the placement allowed for multiple sizes to compete). | |
h | Integer | x | The height of the ad (same as width above). | |
assetsurl | String | x | The URL to retrieve the native assets. See Native Ads section. | |
payload | String | x | x | A unique string to be returned in the notification; it can be up to 1024 characters long. |
clickbrowser | Integer | x | 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. |
Bid Response - Native ads
For Native opportunities, Criteo will fill the assetsurl
with a URL to be triggered after the auction, if won by Criteo. This can be either from the SSP (s2s) or the client device (c2s).
The response to this URL will be a JSON object containing the Creative object (with the assets as well as the event trackers)
CREATIVE OBJECT
Field | Type | Comment |
---|---|---|
image_url | String | URL of the image. |
click_url | String | Click URL. |
title | String | Title of the ad. If you have any length restriction, please contact us. |
description | String | Description of the product. If you have any length restriction, please contact us. |
price | String | Price of the product. It comes formatted by default with the currency symbol. |
imp_trackers | String Array | List of pixel URLs for third-party tracking when available. Pixels to be triggered when the ad has been viewed on the user’s browser. |
view_notice_tracker | String | Pixel URL for Criteo tracking to be triggered when the ad has been viewed on the user’s browser. This pixel contains the price macro to be replaced. |
adchoices | Object | Adchoices object, mandatory |
logo_url | String | URL of Advertiser's logo. |
cta | String | Click-to-action text displayed on a button. |
ADCHOICES OBJECT
Field | Type | Comment |
---|---|---|
image_url | String | URL of the AdChoices icon. Mandatory. |
click_url | String | Link to the custom privacy page. Mandatory. |
long_legal_text | String | Legal text mandatory in Russia. |