App S2S (custom RTB)

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 `tid` (though PreBid.js for example, or Exchange bidding), the SSP should read it and transmit it to Criteo unaltered.
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 `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
creativetype	String	Mandatory	x	x	Creative type of the impression. Could be `banner` or `native`.
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 `1` when the impression is destined to be an interstitial or full-page.
secure	Integer	Mandatory	x	x	Set to `1` if the snipped in the bid response must use HTTPS.
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.

Bid Response - Bid Response Samples

User ID Collection

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

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

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

User ID Collection - First Party IDs

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

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

User ID Collection - Third Party IDs

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

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

User ID Collection - Hashed Emails

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

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

HASHING FORMATS

The hashing should be the users’ email address:

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

Example:

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

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

Table of contents

Introduction

Purpose

Auction Definition

RTB Server-to-Server Protocol

Bid Request

Bid Request - Request Top-Level Object

Bid Request - Auction Object

Bid Request - User Object

Bid Request - Geo Object

Bid Request - Device Object

Bid Request - Publisher Object

Bid Request - App Object

Bid Request - Site Object

Bid Request - Impressions Object

Bid Request - Size Object

Bid Request - Deal Object

Bid Request - Bid Request Samples

Bid Response - Response Top-Level Object

Bid Response - Seatbid Object

Bid Response - Bid Object

Bid Response - Native ads

CREATIVE OBJECT

ADCHOICES OBJECT

Bid Response - Bid Response Samples

User ID Collection

User ID Collection - First Party IDs

User ID Collection - Third Party IDs

User ID Collection - Hashed Emails

HASHING FORMATS