Prebid Client Side (Prebid.js)

Prebid 9 introduces changes that may disrupt existing functionality. Publishers should review these changes before migrating to avoid disruptions to ad revenue. Unlike previous versions, publishers must explicitly enable Criteo to initiate user syncs and configure the Criteo UserId module.

As part of our Commerce Grid rollout, we have introduced new fields for inventory mapping. The CGrid platform will use 'Inventory Groups' to manage your inventory, based in Bidder Params and firstPartyData prebid features.

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.

The information below details how to pass CGrid adunit Ids instead of pub Ids. Integration below only needs to be used for cases where pub Id integration is not sufficient and Adunit mapping is required.

OPTION 1

Publisher should pass the adunit Id from the Grid UI under the adunit config under ortb2Imp.ext.bidder.uid

OPTION 2

Publishers may instead pass this ID through uid 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.

As documented in the Prebid documentation.

To enable Criteo’s proprietary ID solution (Criteo UserId), publishers must install the Criteo UserId module.

This can be done via Gulp:

gulp build --modules=userId,criteoIdSystem,...

Or via the official download page.

The Criteo ID module does not require any configuration parameters. Publishers only need to enable it via setConfig:

pbjs.setConfig({
userSync: {
userIds: [{
name: "criteo",
}]
}
});

Demo Page

Prebid 9 allows publishers to control which bidders can drop user-sync iframes or pixels. To enable a user-sync iframe for Criteo (recommended), publishers must configure it via setConfig.

Demo Page Iframes (recommended) | Demo Page Pixels

Recommended: sending both md5(email) and sha256(email) to Criteo

Supported: sending only sha256(email) to Criteo

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

• source (optional): 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 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 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

Supported: sending a Hashed Phone Number

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

• source (optional) : 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 its hashing method for phone numbers. The expected format for phone numbers should be in trimmed E.164 format, which includes the country code without the leading "+" sign (up to 15 digits): 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 simplify integration for certain partners.

All international formats are accepted, including those with a leading "+" sign. Normalization involves removing all non-numeric characters.

Validation criteria:

• The number may start with a "+" sign.

• It must not exceed 15 digits in length.

• There should be no leading "0", as many countries use "0" as a national dialing prefix.

Afterward, the backend maps the clear phone numbers to SHA256 HPN to ensure uniformity across the accepted formats.

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

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

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

• source: the third party solution domain

• id: the user identifier

• atype (recommended) : 1 for cookie/device based ID, 3 for person-based ID (eg: authenticated user ID, login ID, CRM/customer ID)

• ext.persistence (optional) : js or http

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

• user.data for audience taxonomy data

• site.content.data for contextual taxonomy data in a web environment

Prebid Compliance

You can check the pbjs.setConfig() method on the left.

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 with ortb2.user.data using pbjs.setConfig, please make sure your Prebid version is 6.10+.

Prebid RTD Modules

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

Prebid will provide keywords only for the winning bids:

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

This makes use of the function pbjs.enableSendAllBids() in order 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 especifically:

You will also require 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 left).

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 Account Manager for more details.

Publishers should install the paapi (parent-)module alongside the submodule appropriate for their top-level seller. Currently, there are submodules available for Google Ad Manager (gpt.js) and publisher-designated top-level decision logic.

There are up to 5 steps in the setup

1. Download or build Prebid with support for the paapi and submodule for their desired top level seller

2. PAAPI module configuration

3. Set up a top-level seller

4. AdUnits configuration (optional)

5. Bidder configuration (optional)

Download or build Prebid with the PAAPI modules

Prebid's "paapi" and "paapiForGpt" or "topLevelPaapi" modules must also be included in the build. (link).

The "paapiForGpt" and "topLevelPaapi" module are submodules of the "paapi" (parent-)module which require the "paapi" module to function. Including the "paapiForGpt" or "topLevelPaaapi" module in the build will automatically include the "paapi" module.

This can be done via the downloader on the prebid download page or by using the --modules flag when building prebid.

For more information on how to build prebid, please refer to the prebid github page.

If you build prebid in another way, please make sure the "paapi" module is also included in the build!

Paapi module configuration

Publishers have to enable the paapi parent-module in their Prebid.js configuration. This module exposes the following settings:

PAAPI support is disabled by default. To enable it, publishers need to set the enabled value to true for this module and configure defaultForSlots to be 1 using the setConfig method. Publishers can set an optional default value for the defaultForSlots parameter, which will be used as an auction environment for all adunits that do not have the ortb2Imp.ext.ae flag set. Criteo recommends enabling FLEDGE for all adunits by setting defaultForSlots to 1.

Publisher as top-level seller

Prebid 9 allows publishers to act as top level seller, running the top level auction with their custom decision logic.

Publishers who want to implement this need to install the topLevelPaapi module. (link) This can be done using Gulp gulp build --modules=paapi,topLevelPaapi,...
or the official download page

AdUnits configuration (optional)

All adunits can be opted-in to PAAPI in the global config via the defaultForSlots parameter. If needed, adunits can be configured individually by setting an attribute of the ortb2Imp object for that adunit. This attribute will override the defaultForSlots setting.

Demo Page

Google AdManager (GPT) as Top-Level-Seller

Publishers need to install the paapiForGpt module. This can be done using Gulp: gulp build --modules=paapi,paapiForGpt,...
or the official download page

Demo Page

PAAPI for GPT now supports custom slot matching.

Earlier versions than Prebid 9 had an issue when publishers were using custom slot-matching (the prebid adunit codes are not matching the adunits container div’s id or the google ad-manager adunit path). This lead to criteo counting fledge eligible impressions and also responses with per-buyer-signals but not being able to display fledge impressions.

Prebid 9 now allows publishers to pass their slot-matching function as parameter to setPAAPIConfigForGPT.

Demo Page

AutoConfig Option

The autoConfig option has been removed and replaced with configWithTargeting, defaulting to true, which sets GPT targeting and submits auction configs together. It differs in the previous autoconfig in that it no longer relies on gpt being available at the time of requestBids, only at the time of setTargeting.

Publishers should be aware of this behavior may prohibit submission of auction configuration to GPT sooner than the Prebid.js auction has completed, and will likely prefer to use setPAAPIConfigForGPT.

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

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.

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