Server-Side Ad Insertion (SSAI) | Criteo Commerce Grid Documentation

Introduction

Welcome! This document will explain how to integrate with Criteo’s SSAI server-to-server solution.

Purpose

This Criteo specification is for Server-Side Ad Insertion vendors or other ad tech platforms integrating who want to integrate via OpenRTB to CGrid specifically for video inventory in Connected TV or OTT environment.

If you have any question 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 being sent to Criteo (among other buyers),
Criteo returning a bid response,
The partner selecting a winner (if any),
The partner allowing the winner to display an ad to the user,
The partner returning feedback to Criteo.

Each of these steps will be specified in this document, along with parallel but equally important operations such as user matching and billing.

Server-to-Server Protocol

Criteo uses JSON and the HTTP POST method.

Criteo returns HTTP 204 to signal that it doesn’t want to enter the auction.

User Sync

Please note that user sync can be set up by reaching out to your technical account manager.

Filtering

If you have the ability to do it, please filter out any traffic corresponding to the sections below.

User filtration

Unless instructed otherwise, Criteo should only receive bid requests containing an addressable ID from a Criteo perspective:

the user is matched with a Criteo UID provided in user.buyeruid
the EIDS array contains an ID which source contains criteo (ex: criteo.com, esp.criteo.com)
the EIDS array contains a RampID which source is liveramp.com (the RampID needs to be decrypted by the partner using Sidecar)
the EIDS array contains a UID2.0 which source is uidapi.com
the EIDS array contains a NetID which source is netid.de
a Criteo RTUS ID is available and passed in user.ext.rtusid
an hashed email is available and included following these specs
an IFA is available (IDFA or GAID) and included in device.ifa

Privacy restrictions (DNT/LMT/COPPA)

Please filter out traffic corresponding to at least one of the followings:

"device.dnt" = 1
"device.lmt" = 1
"regs.coppa" = 1

Mobile-web interstitial

Please filter out traffic corresponding to the combination of the 3 followings:

Mobile (ex: "device.os" = "iOS" or "Android")
Web (ex: "site.page" exists)
Interstitial (ex: "instl" = 1)

Blocklisting API

Please filter out traffic which is linked to the list stored in blocklisting API. For more details, please refer to the Blocklisting API section.

Bid Request

To invite Criteo to enter an auction, the partner will be provided with a set of URLs (“endpoints”), each of them pointing to a different Criteo data center. The general intent is that the data center closest to the user should be used, please contact Criteo for more details.

Example endpoint

https://grid-bidder-global-1.us.criteo.com/openrtb/{PLATFORM}/auction/request?profile=332&networkid={NETWORK_ID}

Only one bid request should be sent for a given auction, but multiple auction slots can be included within a bid request. The JSON file should have the structure below and top-level content.

Note:

Mandatory fields must be included.
Recommended fields have positive impact on bidding pattern when implemented properly.
Optional fields have positive impact on operations and reporting.

Bid Request - Top Level Object

Field	Type	Status	Comment
id	String	Mandatory	An identifier for the request, it can be used to connect the bid request to the bid response outside of the HTTP protocol.
imp	Object Array	Mandatory	See Imp object.
app	Object	Mandatory for In-App	See App object.
device	Object	Mandatory	See Device object.
user	Object	Mandatory	See User object.
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.
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
wlang	array of strings	Recommended	Allowed list of languages for creatives using ISO-639-1-alpha-2. Omission implies no specific restrictions, but buyers would be advised to consider language attribute in the `Device` and/or `Content` objects if available. Only one of `wlang` or `wlangb` should be present.
wlangb	array of strings	Recommended	Allowed list of languages for creatives using IETF BCP 47I.
cattax	integer	Recommended	The taxonomy in use for `bcat`. If no cattax field is supplied, the IAB Content Category Taxonomy 1.0 (`1`) is assumed. For the most up to date list, refer to the AdCOM 1.0 List.

Bid Request - Source Object

Field	Type	Status	Comment
fd	Integer	Recommended	Entity responsible for the final impression sale decision, 0 = exchange / 1 = upstream source
tid	String	Recommended	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` (through 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.
schain	Object	Mandatory	Enable buyers to see all parties who are selling or reselling a given bid request. More information can be found here.
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 partner: 2, Amazon TAM: 3, EBDA: 4, Prebid: 5, Index HB: 6, Other HB solution: 7

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	Contains the Global Privacy Platform’s consent string. See the Global Privacy Platform specification for more details.
gpp_sid	array of integers	Recommended	Array of the section(s) of the string which should be applied for this transaction. Generally will contain one and only one value, but there are edge cases where more than one may apply. GPP Section 3 (Header) and 4 (Signal Integrity) do not need to be included. See the GPP Section Information for more details.

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 in the imp array.

Please note that imp.exp has a default value set to 3 hours.

Field	Type	Status	Comment
id	String	Mandatory	A unique identifier for this impression within the context of the bid request (typically, starts with 1 and increments).
metric	Object Array	Recommended	See Metric object.
video	Object	Mandatory for video	A Video object is required if this impression is offered as a video ad opportunity.
audio	Object	Mandatory for audio	An Audio object is required if this impression is offered as an audio 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, SSAI 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	Recommended	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
rwdd	integer	Mandatory for In-App and `plcmt`	(Note: this field is required for some Buyers in particular DV360) Indicates whether the user receives a reward for viewing the ad, where `0` = no, `1` = yes. Typically video ad implementations allow users to read an additional news article for free, receive an extra life in a game, or get a sponsored ad-free music session. The reward is typically distributed after the video ad is completed.
ssai	int	Mandatory for CTV	Indicates if server-side ad insertion (e.g., stitching an ad into an audio or video stream) is in use and the impact of this on asset and tracker retrieval. It can take the following values: `0` = status unknown `1` = all client-side (i.e., not server-side) `2` = assets stitched server-side but tracking pixels fired client-side `3` = all server-side.
qty	object	Optional	A means of passing a multiplier in the bid request, representing the total quantity of impressions for adverts that display to more than one person
dt	float	Optional	Timestamp when the item is estimated to be fulfilled (e.g. when a DOOH impression will be displayed) in Unix format (i.e., milliseconds since the epoch).
exp	int	Optional	Impression expiration time in seconds, i.e. interval that may elapse between the auction and the actual impression.
ext.gpid	String	Recommended	(Note: this field is required by some buyers including Criteo and The Trade Desk) A unique identifier for the placement of the ad that is the same for all SSPs.
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.publisher_sub_id	string	Optional	Optional inventory identifier to view reporting breakdown
ext	Object	Optional	Placeholder for exchange-specific extensions to OpenRTB.

Fields not supported:

Field	Comment
secure	Criteo will always consider `secure = 1`
iframebuster	Not supported

Bid Request - Metric Object

Field	Type	Status	Comment
type	String	Mandatory	Type of metric being presented using exchange. Eg: "viewability"
value	Float	Mandatory	The value, from 0.0 to 1.0
vendor	String	Mandatory	Source of the value. Eg: "doubleverify.com"

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: Creative Subtypes - Audio/Video in AdCOM 1.0.
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. Refer to List: Start Delay Modes in AdCOM 1.0.
maxseq	Integer	Recommended (Mandatory if using dynamic ad podding)	Indicates the maximum number of ads that may be served into a “dynamic” video ad pod (where the precise number of ads is not predetermined by the seller).
poddur	Integer	Recommended (Mandatory if using dynamic or hybrid ad podding)	Indicates the total amount of time in seconds that advertisers may fill for a “dynamic” video ad pod, or the dynamic portion of a “hybrid” ad pod. This field is required only for the dynamic portion(s) of video ad pods. This field refers to the length of the entire ad break, whereas `minduration/maxduration/rqddurs` are constraints relating to the slots that make up the pod.
podid	Integer	Recommended	Unique identifier indicating that an impression opportunity belongs to a video ad pod. If multiple impression opportunities within a bid request share the same `podid`, this indicates that those impression opportunities belong to the same video ad pod.
podseq	Integer	Recommended (Mandatory if using dynamic or hybrid ad podding)	The sequence (position) of the video ad pod within a content stream. The following values are supported: `-1`: Last pod in the content stream `0`: Any pod in the content stream `1`: First pod in the content stream
rqddurs	Array of integers	Optional	Precise acceptable durations for video creatives in seconds. This field specifically targets the Live TV use case where non-exact ad durations would result in undesirable ‘dead air’. This field is mutually exclusive with `maxduration`.
placement	Integer	Deprecated	Deprecated, use plcmt Placement type for the impression.
plcmt	Integer	Mandatory	Placement type for the impression, for example `2`. Note: Though not required, this is an important field for some Buyers, not explicitly setting it will result in lower demand. Refer to List: Plcmt Subtypes - Video in AdCom 1.0.
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.
slotinpod	Integer	Recommended	For video ad pods, this value indicates that the seller can guarantee delivery against the indicated slot position in the pod. The following values are supported: `-1`: Last ad in the pod `0`: Any ad in the pod `1`: First ad in the pod `2`: First or last ad in the pod
mincpmpersec	Float	Recommended (Mandatory if using dynamic or hybrid ad podding)	Minimum CPM per second. This is a price floor for the “dynamic” portion of a video ad pod, relative to the duration of bids an advertiser may submit.
battr	Integer array	Recommended	Blocked creative attributes. Refer to List: Creative Attributes in AdCOM 1.0.
maxextended	Integer	Recommended	Maximum extended video ad duration if extension is allowed. Blank or `0`, extension is not allowed. `-1`, extension is allowed, and there is no time limit imposed. Greater than `0`, then the value represents the number of seconds of extended play supported beyond the `maxduration` value.
minbitrate	Integer	Optional	Minimum bit rate in Kbps, for example `680`
maxbitrate	Integer	Optional	Maximum bit rate in Kbps, for example `990`
boxingallowed	Integer	Optional	Indicates if letter-boxing of 4:3 content into a 16:9 window is allowed: 0 = no 1 = yes.
playbackmethod	Array of integers	Mandatory	Allowed playback methods as defined in the OpenRTB, for example `[1, 2]`. If none are specified, it is assumed all are allowed. Please refer to List: Playback Methods in AdCOM 1.0
playbackend	Integer	Optional	The event that causes playback to end. Refer to List: Playback Cessation Modes in AdCOM 1.0.
delivery	Array of integers	Recommended	Supported delivery methods (e.g., streaming, progressive) as defined in OpenRTB. If none specified, assume all are supported, for example, `[1, 2]`
pos	Integer	Recommended	Ad position on screen. Refer to List: Placement Positions in AdCOM 1.0.
companionad	Object array	Recommended	Array of Banner objects if companion ads are available. See the Banner Object section for more information.
api	Array of integers	Mandatory	List of supported API frameworks for this impression as defined in OpenRTB, for example, `[1,2]`. If an API is not explicitly listed, it is assumed not to be supported. Please refer to List: API Frameworks in AdCOM 1.0
companiontype	Array of integers	Recommended (Mandatory if `companionad` is declared)	List of allowed companion ad types, for example `[1, 2]` Possible values: `1`: Static Resource `2`: HTML Resource `3`: iframe Resource
ext	Object	Optional	Extension to OpenRTB Video object.