Skip to main content

Standalone / Publisher tag

Commerce Grid DocumentationIntegration Guides WebStandalone / Publisher tag
Table of contents

Welcome! This document will explain integrating with Commerce Grid's Standalone / Publisher Tag solution.

Criteo provides a piece of code to be added in the header of the pages before the ad server callout. This generates an asynchronous call so Criteo can identify the user and return a bid. This information, including the bid price, is then sent to the ad server.

Criteo campaigns are targeted in the ad server based on Custom keyword criteria.

Requirements

You will receive from Criteo:

  • A script library to be placed on the header of your pages

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

  • Code samples demonstrating how to initialize the Criteo tag and how to map the placements

  • Creative codes to be used in the ad server

We will need you to:

  • Implement the scripts on the page header

  • Map the placements available on each page and use it to initialize our tags

  • Create the line items for the different bid prices in your ad server

  • Implement the targeting rules and the creative code

  • Criteo complies with the IAB Consent Framework. Please refer to their documentation for more information and examples of certified CMPs.

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.

ad unit code

format

Criteo zone id

ad-unit-0

300x250

775590

ad-unit-1

728x90

775591

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

Parameter

Example

Description

Host

http://www.publisher.com

This is the page domain

Referer

http://www.publisher.com/my/page

This is the request referer

Form Data

{"publisher":{"url":"http://www.publisher.com/my/page"},"slots":[{"impid":"ad-unit-0","zoneid":775590},{"impid":"ad-unit-1","zoneid":775591}]}

Adunits mapping

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 :

Field

Type

Description

Example

impid

String

The adunit id provided in the request

ad-unit-0

cpm

Float

The raw bid CPM

1.58

displayurl

String

The JS creative URL

"http://cas.criteo.com/delivery/r/ajs.php?did=..."

zoneid

Integer

The Criteo zoneid provided in the request

775590

width

Integer

The creative width

300

height

Integer

The creative height

250

native

Object

Optional Native assets

See assets section

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 :

Keyword

Type

Description

Example

crt_bidid

String

An unique random identifier for the bid

&crt_bidid=tyvxvh

crt_pb

String

The bid price band CPM

&crt_pb=3.50

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:

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 that 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) "http" if the 1PC was set through an HTTP Set-Cookie directive or "js" if the 1PC was set through JavaScript (either in a cookie or in the local storage).

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