Standalone / Publisher tag

This code initializes the Criteo tags to make your inventory available to Commerce Grid's demand sources. The code will load the publishertag.js library and build the events queue that will be used later. The loader request is asynchronous and is cached on the user's browser. No code changes are required in this section.

The next step is to map all the ad units available on the page and assign their code to their respective Criteo ID.

A global placement identifier (GPID) is a publisher-specified placement (tag) ID that is passed unchanged by all supply-side platforms (SSPs).

The mapping is now used to generate a bid request to Criteo's endpoint.

• Criteo.events.push(function() { : The code wrapped inside this function is added to the Criteo.events queue that will be processed asynchronously as the page loads, allowing our bid to be inserted prior to ad server decisioning

• Criteo.SetLineItemRanges("[min1]..[max1]:[increment1];[min2]..[max2]:[increment2];"); : This defines the price band granularity which will be sent to the adserver. Must begin with 0. Three common examples below:

  • Criteo.SetLineItemRanges("0..3:0.01;3..8:0.05;8..20:0.50;20..30:1.00"); - Single Order with 434 LI

  • Criteo.SetLineItemRanges("0..10:0.01;10..25:0.05;25..50:0.10;50..100:0.25"); - 1750 LI in 4 Orders

  • Criteo.SetLineItemRanges("0..50:0.01;50..100:0.20"); - 5250 LI in 12 Orders

• Criteo.RequestBids([adunits], [callBack], [timeout]); : This will send a browser request for the given adunits and will execute the callback function callBack as soon as Criteo responds or the timeout is triggered

HTTP REQUEST

The code above will finally build a request to bidder.criteo.com sending the adUnits in the HTTP POST header

HTTP RESPONSE

In case Criteo has a bid for the user, the request above will return a HTTP STATUS 200 with an array of slots object described below :

In case the user is not eligible for any Criteo campaign, the bid response will be an empty response.

The callback function is executed as soon as the bid response is received. The bids must now be processed and sent within the adserver request. The examples from now on will use DFP as a reference, but this can be adapted to any adserver that supports keyword targeting.

The adserver request must wait for the Criteo bidder to respond first. This can be achieved by using a combination of two functions:

• disableInitialLoad() : This will prevent the Adserver from being charged automatically as the page loads

• googletag.pubads().refresh() : This will be used to finally trigger the adserver call after the Criteo bid response or if the timeout is reached

More details on DFP's documentation here

This can be implemented in the callback function that will be triggered once the Criteo bid response is received (or after the timeout). On our previous example, we are using the function named launchAdServer.

• Criteo.RequestBids(adUnits, launchAdServer, 700); triggers the bid request

• launchAdServer is executed within 700 ms or less depending on how fast Criteo responds

• The auxiliary function Criteo.SetDFPKeyValueTargeting() automatically parses the response and sets placement-level keywords to the adserver :

Complete example:

You will find a full example on this page

To enrich the bid request data with user IDs (first-party user IDs, third-party IDs, or hashed emails), please use the function Criteo.SetIdentities as described in the sections below.

This function accepts an array of OpenRTB EIDS objects as input:

Use the function Criteo.SetIdentities 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 Criteo.SetIdentities 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

Use the function Criteo.SetIdentities 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: 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 lowercase

• 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

Use the function Criteo.SetIdentities providing the data below (example 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 the integration.

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

Go to Inventory > Key-values and click on New Key and create the key-value

• Key name: crt_pb

• Value type: Users will enter targeting values when creating line items or checking inventory. (Free-form)

Go to Delivery > All orders and click on New Order and create one new Order for the Commerce Grid inventory integration.

You can create the first line on the same page. The goal is to create one dedicated line item per different CPM price bands.

We will create the unitary CPM for this first line item:

• Name: Please use a self-explanatory name like chb_1.00

• Inventory sizes: Please include all formats available on your page. Eg: 728x90, 300x250

• Labels section: Please check Allow same advertiser exception

• Type: Please select the priority as agreed with your Criteo representative.

• Start time: Immediately

• End time: Unlimited

• Limit: None

• Rate: Please include here the CPM. On this first example, we will use $1.00

• Display Creatives: One or More.

• Rotate Creatives: Evenly

Finally, please select the inventory for the campaign and add the following targeting:

• Type: Choose Key-values

• Select a key: Choose crt_pb

• Value: choose is and input 1.00

Finally, hit save and follow with the creative steps below.

Go to Delivery > Creatives > All creatives and click on Add creative and type the same advertiser name.

• Type: Third-party

• Name: CDB_OnPage_Creative1

• Code snippet: paste the code located on the right

• Size: 1x1

• Please untick the SafeFrame mode

Hit Save.

Go back to the first line item created, click on the Creatives tab and on use existing creatives.

Click on Show all and you will be able to list and include the recently created one.

Go back to this creative settings (Creatives tab > Click on the creative > Settings) and update the Size overrides with all the formats available on your page.

The last step is to duplicate this creative as many as unique ad units you have on the same page. I.e.: Should you have up to 5 different ad units on your homepage, this means you will need to setup at least 5 creatives for this line item.

The easiest way to achieve this is by selecting one (or multiple) creatives and click on More actions > Copy creative until you have the minimum amounts required.

Now that you have the first line item fully configured, you can simply duplicate it and reuse the existing creatives. To do so, go to the line item pages, select its respective checkbox, and click on More actions > Copy and share creatives. Repeat this action for all the different price bands you have.

Please don't forget to update:

• The line item name

• The CPM

• The keyword targeting the respective price band

You can edit those values directly from the list page by clicking on the icon on the corner of each field:

• Line item name

• CPM

• Inventory and keyword targeting

• Start date. Please double-check this value as the default one is the next day!

Once you are set, select all the new line items and click on the Resume button.

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

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

NATIVE OBJECT

PRODUCT OBJECT

IMAGE OBJECT

ADVERTISER OBJECT

PRIVACY OBJECT

IMPRESSION PIXEL OBJECT

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

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.

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.

Complete example

You will find a full example on this page. Please check the source-code around the <!-- Criteo bidder --> area

Ad unit mapping is required for video. Make sure to properly set up the mediaTypes.video object as shown in the example. Refer to the Video Object for a full list of parameters.

Google Ad Manager Integration

The Criteo.SetDFPVideoKeyValueTargeting function is a helper method which will append Criteo key-values to your existing GAM Vast url. Once the url is enriched, it is ready to be passed to your instream player for rendering.

Note: The gamUrl in the example is a sample GAM Vast tag. Replace with your own Vast tag!

Other Ad Servers Integration

The RequestBids callback will contain the returned bids where you will have access to the full bid object (i.e cpm, vastUrl) to handle as needed. Refer to Video Bid Object to see the list of parameters available.

For outstream rendering with your own renderer, make sure you've set up the videoCallback function in your Video Placement mapping.

Outstream integration is set up similarly to a standard banner integration. Bids are requested, and upon returned Criteo key-values are appended to the ad call.