Skip to main content
Table of contents

Introduction

Welcome! This document will explain integrating Commerce Grid into your existing Prebid Server.

If you are starting from scratch, please refer to Prebid’s documentation for Prebid Server here.

To enable Criteo as a Prebid Server Bidder, you must already set up a Prebid Server instance. You may be using a hosted managed service, such as the solutions provided by providers here, or you may host your own prebid server instance.

To learn more about how Prebid Server works, see Prebid documentation here.

Requirements

  • Prebid Server:

    - For GO : v0.256.0 or higher (as we added iframe based user-sync in v0.256.0).

    - For JAVA : v1.121.0 or higher (corresponds to the GO version).

  • A list of identifiers for each ad placement and/or format you have available on the page.

Registering the Criteo bidder

If you are using a Prebid managed service, the enablement and params may be set up in the UI of the provider instead of through code directly.

For Criteo Commerce Grid params, you will need to enter the networkId which can be provided by your Criteo Commerce Grid contact.

Registering the CGrid Criteo bidder - Publisher ID setup

Each inventory group will be tied to a Publisher ID. Publisher ID can be a unique ID provided by the publisher and mapped on Criteo side, or by default we will use the ID provided for ads.txt.

Option 1

Publisher ID can be passed through ortb2.site.publisher.id to bidder config.

Option 2

As of Prebid v9.4.1 publishers may instead pass this ID through pubid under Criteo bid params, along with networkId. Note that receiving the id under ortb2 object as above is still supported as well so publishers can choose either option.

Note that as of now networkId is a required parameter to pass along with pubId through bid params. See example.

Registering the CGrid Criteo bidder - Ad Unit ID Setup

The information below details how to pass CGrid Ad Unit IDs instead of Publisher IDs. Integration below only needs to be used for cases where publisher ID integration is not sufficient and ad unit mapping is required.

Publishers should pass this ID through uid under Criteo bid params along with networkId.

Note that as of now networkId is a required parameter to pass along with pubId through bid params. See example.

Global Placement ID (GPID)

As documented in the Prebid documentation, you will need to register Criteo's bidder for each of your ad units. You will find an example to the right.

Please include the Criteo bidder and the networkId provided by your Commerce Grid Account Manager on the top of the bids array for the respective adunit.

User ID Collection

As documented in the Prebid documentation, Criteo Commerce Grid collects all IDs generated by Prebid User ID modules, including SharedID and other third-party ID solutions.


If you are using SharedID, please consider implementing SharedId First Party endpoint to make the ID more persistent.

To enrich the bid request data with user IDs not available via these modules (first-party user IDs, third-party IDs, or hashed emails, for instance), please use pbjs.setBidderConfig() to pass an eids array as explained in the below sections.


The eids field should be an array of OpenRTB EIDS objects.

User ID Collection - User Syncing

Proper user matching is crucial to make a Prebid Server connection successful. We support both redirect-based and iframe-based user sync, so to ensure optimal user matching you can leverage either or both of them.

Links to our bidder and user sync endpoints can be found in our YAML file: https://github.com/prebid/prebid-server/blob/master/static/bidder-info/criteo.yaml

Note: In order for user sync to work, we will need to allowlist your host to call our sync endpoints, therefore please reach out to your technical account manager and share your host so we can activate on our side.

User ID Collection - Criteo Id Module


Criteo Id Module is a lightweight identity module which allows Criteo to grab the Criteo Id which can be passed to exchanges. Implementing this module will improve user match rates.

User ID Collection - Prebid.js 6.23+ versus older versions

The below examples on the right correspond to the supported way to pass the "eids" array on Prebid.js 6.23+, including Prebid.js 7, namely via "ortb2.user.ext.data.eids".
On Prebid.js 6.23+, our bid adapter also supports "ortb2.user.ext.eids" which corresponds to the OpenRTB standard.

User ID Collection - Hashed Emails

Use the function pbjs.setBidderConfig() providing the data below (examples on the right):

  • (optional) source: your domain or the domain of the solution operating on your behalf

  • id: the hashed email

  • atype: 3

  • ext.stype: hashing algorithm used: cleartextemail, hemsha256, hemmd5, hemsha256md5. Please refer to the 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 lowercase

  • Hashed with MD5 or SHA256 or 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

User ID Collection - Phone Numbers

Use the function pbjs.setBidderConfig() providing the data below (examples on the right):

  • (optional) source: your domain or the domain of the solution operating on your behalf.

  • id: the user data

  • atype: 3

  • ext.stype: hashing algorithm used. It can be either pnclear if the phone number is hashed, or pnsha256 if the phone number is in clear. Please refer to next section for details on hashing formats.

HASHED PHONE NUMBERS

Criteo uses SHA256 as a hashing method. The expected underlying phone numbers format is trimmed E.164 format, including the country code, without the leading "+" sign (so only 15 digits, at most): sha256(internationalPhoneNumber.replaceAll(/[^0-9]/g, "")).

Example:

  • 1 (234) 567-8910 → sha256(12345678910) → 63640264849a87c90356129d99ea165e37aa5fabc1fea46906df1a7ca50db492

  • 81-12-3456-7891 → sha256(811234567891) → d9825fb05347d3c910fc5202c0c20d07a87b791cc643c6f2d70402394a849540

  • 02 1234 5678 → sha256(0212345678) → 826f54894e28f3f1795f3c5e3335cf98709c5d5b38b3f9c6d72467d491f032df

  • +33 1 40 40 22 90 → sha256(33140402290) → fda66831d0cb0eb4bffb21bc795308d69921c211c57be0ae15702071e3b9e988

CLEAR PHONE NUMBERS

Clear phone numbers are accepted to ease integration for some partners.

Any international formats are accepted (including the leading "+" sign). Normalization remove all non numeric characters

Validation checks:

Number starts with a + sign length is at most 15 digits there is no leading 0: many countries use 0 as national dial number Then backend map the clear phone numbers to SHA256 HPN so the two accepted formats are uniform.

Examples:

  • +1 (234) 567-8910

  • +81-12-3456-7891

  • +33 1 40 40 22 90

  • 02 1234 5678 is rejected because of a leading 0 indicating that it is a national phone number

User ID Collection - First Party IDs

Use the function pbjs.setBidderConfig() providing the data below (examples on the right):

  • source: your 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

Use the function pbjs.setBidderConfig() providing the data below (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 - Custom data segments

Criteo Prebid adapter supports 2 main bid request object nodes for sellers defined data:

PREBID COMPLIANCE

In order to pass the custom cohorts data using one of the oRTB2.5 objects mentioned above, please use the pbjs.setConfig() method as the example aside.

In order to comply with the method for passing real-time data by ortb2.user.data using pbjs.setConfig, please make sure your Prebid.js version is 6.10+.

PREBID RTD MODULES

The Criteo bid adapter is by default integrated with any real-time data (RTD) Prebid module that utilizes the ortb2 object to store and pass the audience and context information, for example, the JW Player and Permutive modules.

Google Ad Manager Setup

If this is the first time you are setting up a Prebid campaign in Google Ad Manager, please contact your Criteo Commerce Grid Account Manager for help.

Please check the official Prebid documentation here for a detailed step-by-step description.


You can integrate Prebid in two modes.

Google Ad Manager Setup - Standard - Mediation mode on - Not recommended

Prebid will provide keywords only for the winning bids:

Keyname

Example

Description

hb_bidder

hb_bidder=criteo

The winner

hb_adid

hb_adid=xxxyyyzzz

The ad Id used by the ad server creative to render the correct ad

hb_pb

hb_pb=2.50

The bid price bucket used to target the respective line item.

hb_size

hb_size=300x250

The ad format

hb_format

hb_format=video

Used when creating a separate set of line items for banner vs video

hb_deal

hb_deal=7777777

Target private marketplace deals

hb_uuid

hb_uuid=1111-2222-3333-4444

Carries the cache retrieval ID for VAST video creatives

hb_cache_id

hb_cache_id=2222-3333-4444-5555

Carries the cache retrieval ID for mobile bids

hb_cache_host

hb_cache_host=https://mycachehost.example.com

The host where the cached creative lives

hb_cache_path

hb_cache_path=/cache

The web path where the cached creative lives

hb_source

hb_source=s2s

Used to report the A/B test results for client- vs server-side performance

hb_adomain

hb_adomain=example.com

Used to report on VAST errors, set floors on certain buyers, monitor volume from a buyer, or track down bad creatives

The keyword hb_pb is used to define the line item targeting criteria (image below), and hb_adid at the creatives (code to the right).

hb_pb (1).png
16.5 KB

Google Ad Manager Setup - Send all bids - Mediation off - Recommended

This makes use of the function pbjs.enableSendAllBids() to provide keywords for all bidders. More details on http://prebid.org/dev-docs/examples/send-all-bids.html and http://prebid.org/adops/send-all-bids-adops.html

For Criteo specifically:

Keyname

Example

Description

hb_adid_criteo

hb_adid_criteo=xxxyyyzzz

The ad Id used by the ad server creative to render the correct ad

hb_format_criteo | hb_format_criteo=banner | This will ensure that the appropriate ad server line item is activated for banner / out stream bids hb_pb_criteo | hb_pb_criteo=2.50 | The bid price bucket used to target the respective line item. hb_size_criteo | hb_size_criteo=300x250 | The ad format

You will also be required to implement one dedicated set of line items for Criteo using the keyword hb_pb_criteo for the line item targeting criteria (image below), and hb_adid_criteo at the creatives (code to the right).

hb_pb_criteo (1).png
17.1 KB

Google Ad Manager Setup - Line item Creation tool

Criteo offers a tool to help doing the initial Prebid setup. You will need to enable API access and share Google Ad Manager access with Criteo. Please contact your Criteo Commerce Grid Account Manager for more details.

Video

Criteo supports video ads. Please refer to this guide for more details.

Native ads

We recommend to use Prebid.js native implementation. Please refer to this official Prebid guide for more details.

Native ads - Ad requirements

Native guidelines for Commerce Grid:

  • Display the Ad Choices icon and implement the link to the opt-out page

  • Display at least one advertiser information (domain, name)

  • Display at least one product recommendation

  • Use Criteo to click URLs

  • Every impression pixel must be called once the ad is delivered.

Native ads - Product images


Criteo images for native inventory will be sized to fit within a 400x400 html element. They will not be padded to fit the dimensions or ratio, they should therefore be centered in the layout by the partner.

Native ads (deprecated) - Native Placement

The original native implementation described below is still valid but we discourage its use.

In order to activate Native demand, first you need to declare a callback function that will be used to render the Native ad. This section provides instructions on how to build a native ad.

Native ads (deprecated) - Native Object

When a native demand is available, Criteo will return the following native object:

NATIVE OBJECT

Field

Type

Description

product

Product object Array

List of product assets.

advertiser

Advertiser object

Includes the adv name and logo

privacy

Privacy object

Includes adchoices and opt-out url

impression_pixels

Impression pixels object Array

List of impression pixels

PRODUCT OBJECT

Field

Type

Description

title

String

Product title.

description

String

Product description.

price

String

Product formatted price. It comes formatted by default with the currency symbol.

click_url

String

Product landing page

call_to_action

String

Product CTA

image

Image object

Product image (400x400 px)

IMAGE OBJECT

Field

Type

Description

url

String

Image URL.

height

Integer

Image height

width

Integer

Image width

ADVERTISER OBJECT

Field

Type

Description

description

String

Advertiser name

domain

String

Advertiser domain

logo

Image object

Advertiser logo (200x200 px)

PRIVACY OBJECT

Field

Type

Description

optout_click_url

String

Opt-out landing page URL

optout_image_url

String

Adchoices icon URL

IMPRESSION PIXEL OBJECT

Field

Type

Description

url

String

Impression pixel beacon

Native ads (deprecated) - Adserver integration


The campaigns are configured as the normal campaign and you can reuse the same Creative codes for the standard ads. Prebid will automatically identify the native ad context and execute whatever has been defined at the nativeCallback parameter.

Native ads (deprecated) - Ad requirements

Criteo Native guidelines:

  • Display the adchoices icon and implement the link to the opt-out page

  • Display at least one advertiser information (domain, name)

  • Display at least one product recommendation

  • Use Criteo click URLs

  • Every impression pixel must be called once the ad is delivered

You will find to the right one sample code that uses the most relevant assets.

Native ads (deprecated) - Product images

Criteo images for native inventory will be sized to fit within a 400x400 html element. They will not be padded to fit the dimensions or ratio, they should therefore be centered in the layout by the partner.

Native ads (deprecated) - Complete example

You will find a full example on this page.