Criteo Server To Server - Website Events¶

Summary¶

A Server-to-Server (S2S) integration is the go-to solution for partners that can not or will not integrate the Criteo OneTag JS pixels on their website for technical, legal, or personal reasons.

As a prerequisite, the partner must be able to store their event data locally. A S2S integration relies on the partner passing us first-party data, so a S2S integration is not possible unless the partner can store this data.

A S2S Integration requires 2 parts: (1) the Cookie Synchronization, and (2) Events Registering.

1. Cookie Synchronization: requesting a unique ID from Criteo (called the "GUM ID" from now on) for each user, and storing this value in the browser.

2. Events Registering: sending each event with the matching GUM ID and the correct event data to the Criteo S2S endpoint as an HTTP GET or POST request.

The S2S integration can be separated into 3 Phases (divided into 4 parts below).

Prerequisites:

• Stored Events: Partner must be able to store the on-site events and GUM ID locally.

Cookie Synchronization:

• Criteo Gum Call: Partner must request Criteo GUM ID for all on-site visitors and then store Criteo GUM ID in browser local storage and in a 1st party cookie.

Event Registering:

• Sending S2S Event: Partner must pass Criteo the event and user data using our S2S endpoint. This must be done in real-time or near-real-time.

The image below demonstrates where each part comes into play

Stored Events¶

There are 2 common setups when integrating via S2S

• Sending all on-site events via S2S
• Sending only select events (e.g. only sending Sales Events via S2S)

In either case, the partner is responsible for collecting the necessary on-site browsing data so that it can later be passed to Criteo via S2S.

This is not usually a problem for most clients as their first-party data is typically readily available to the partner in a multitude of formats.

For this reason, we will not explain the process of recording this event data or first party identifier any further.

Criteo GUM Call¶

The first implementation step for S2S is to request a unique, salted, Criteo User ID (aka GUM ID) for each user.

• The same user can receive multiple different GUM IDs, but all GUM IDs will be matched to the same Criteo user.
• This request should be made every time a page is loaded, persisting updated GUM ID values in the browser.
• This call must be sent client side so we can set a 3rd party cookie on the users browser.

The URL to request a GUM ID has the following syntax:

https://gum.criteo.com/sync?c={{S2S ID}}&a=1&r=[0-3](&u=[URL])(&j=[callback])

• We will go over in detail what each query parameter means later in this documentation.

As an example, if we visit https://gum.criteo.com/sync?c={{S2S ID}}&a=1&r=0, then the plaintext GUM ID will be returned.

Query parameters for the GUM call:

• c: partner specific S2S Id (used for salting the Criteo UID).
  • This will be hardcoded for all GUM calls.
• a: 0 or 1.
  • 1 means Criteo should generate a UID if no UID exists for a given user
  • for almost all cases, 1 should be passed.
• r: response type. This will determine how the GUM ID is returned by Criteo. Should always be set to 2 in production.
  • 0: plaintext (testing purposes only. CORS will block this in production)
  • 2: JSONP

Once the GUM ID is returned by Criteo, it should be stored in a 1st party cookie and in local storage for use when sending events to Criteo.

Format of Request Using JSONP Mode (r=2):

https://gum.criteo.com/sync?c={{S2S ID}}&a=1&r=2&j=[callback]

j: the javascript function name to pass the response to.

• the GUM ID will be passed into the callback function defined as the j parameter which should then process the GUM ID and store it in a first party cookie and in local storage.

Example JSONP call:

https://gum.criteo.com/sync?c={{S2S ID}}&a=1&r=2&j=_handleGumResponse

Storing the GUM ID¶

After the partner requests the GUM ID from Criteo, the next step is to store this ID into a first party cookie and into Local Storage. The GUM ID should be stored in both a first party cookie and local storage to make the solution more persistent.

Sending Events¶

Sending events via S2S is not very different than sending them in real time (excluding the time delay).

• OneTag: the on-site Criteo OneTag will collect the necessary info from the site then generate an HTTP quest to the Criteo widget server which will be processed as a tag event
• S2S: The on-site data will be collected by the partner, then the partner will generate an HTTP request to the Criteo Widget server for each event collected which will be processed as a tag hit. Events sent through S2S should be sent to Criteo in real time or near-real-time (within 15 minutes of the event) as our solutions rely on this time window in order to perform successful click attribution.

The event syntax for S2S events is the same as the OneTag syntax, however, we require the partner to pass extra information with the event to allow the S2S event to be registered correctly.

The URL the S2S events will be sent to is:

https://widget.criteo.com/m/event?version=s2s_v0

Note that this call will return an HTTP 307 redirect response to the domain specified below according to the region:

Once the S2S data is formatted, there are two ways to send the data to Criteo.

• via HTTP POST request to the above URL (data in body payload)
• via HTTP GET request to the above URL (data in a "data" query parameters)

HTTP POST Requests:

When sending an event via a POST request, the payload of the request must be set to the JSON object containing the event data.

Below is a sample CURL call containing the bare minimum information for a homepage event. Please reference the "Event Payloads" section below for more parameters and events.

curl --location --request POST 'https://widget.criteo.com/m/event?version=s2s_v0' \
--header 'Content-Type: application/json' \
--data-raw '{
    "account":"XXXX",
    "site_type":"m,d,or t",
    "id":{
        "mapped_user_id":"XXXXXX",
        "mapping_key":"XXX"
    },
    "events":[
        {
            "event":"viewHome"
        }
    ],
    "version":"s2s_v1.0.0"
}'

HTTP GET Requests:

When sending requests via a GET request, you will be making use of the data query parameter. The data query param should contain a URL encoded JSON object containing the S2S event data.

Below is a sample CURL call containing the bare minimum information for a homepage event. Please reference the "Event Payloads" section below for more parameters and events.

curl --location --request GET 'https://widget.criteo.com/m/event?version=s2s_v0&data=%7B%0A%20%20%20%20%22account%22%3A%22XXXX%22%2C%0A%20%20%20%20%22site_type%22%3A%22m%2Cd%2Cor%20t%22%2C%0A%20%20%20%20%22id%22%3A%7B%0A%20%20%20%20%20%20%20%20%22mapped_user_id%22%3A%22XXX%22%2C%0A%20%20%20%20%20%20%20%20%22mapping_key%22%3A%22XXX%22%0A%20%20%20%20%7D%2C%0A%20%20%20%20%22events%22%3A%5B%0A%20%20%20%20%20%20%20%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20%22event%22%3A%22viewHome%22%0A%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%5D%2C%0A%20%20%20%20%22version%22%3A%22s2s_v1.0.0%22%0A%7D'

Event Identifiers¶

Identifiers must be explicitly provided in all data payloads when sending event data via S2S calls. In web payloads, identifiers are made available through browser cookies, but HTTP requests coming from a server wouldn't have a cookie identifier present in the HTTP headers.

Each S2S event requires passing through an id node in the payload with 1 of 4 possible identifier types inside of it. The types that can be provided are idfa, gaid, mapping_key with mapped_user_id, or email. One identifier is required for any payload (otherwise the event won't be addressable), but only one should be provided in the id node.

If a hashed email is available for a payload in addition to 1 of the other 3 identifiers then it can be passed in the alternate_ids node. Criteo accepts emails hashed with SHA256, MD5, and SHA256(MD5). If emails are not hashed they will be hashed before storage to meet our privacy standards for data. Providing this field allows for cross-device attribution when available and may enable addressing events without a mapped_user_id. Note that the field itself is optional, but the fields in the hashes in the alternate_ids array are all required.

Event Payloads¶

Every S2S call sent to Criteo will start with the same format. Below is the standard format of the payload without the event declared.

{
  "account": "",
  "ip": "",
  "full_url": "",
  "site_type": "",
  "user_agent": "",
  "retailer_visitor_id": "",
  "id": {
    "mapping_key": "",
    "mapped_user_id": "",
    "idfa": "",
    "gaid": "",
    "email": {
      "raw": "",
      "md5": "",
      "sha256_md5": "",
      "sha256": ""
    }
  },
  "alternate_ids": [
    {
      "type": "",
      "hash_method": "",
      "value": ""
    },
    ...
  ]
  "events":[
    ## Event Object From Below ##
  ],
  "version":"s2s_v1.0.0"
}

Required fields are used to support attribution, address audiences across display environments, and detect fraudulent traffic.

The table below has the values required to populate elements in the alternate_ids array with hashed email(s). Note that the alternate_ids field itself is optional, but the fields in the hashes in the "alternate_ids" array are all required for each hash in the array.

Please reference the other sections below to populate the events array with tags.

Standard Web Events:¶

{
  "event": "viewPage",
  "timestamp":""
}

{
  "event": "login",
  "timestamp":""
}

{
  "event": "viewHome",
  "timestamp":""
}

{
  "event": "viewList",
  "item": [ 
    "##Product Id 1##", 
    "##Product Id 2##", 
    "##Product Id 3##" 
  ],
  "timestamp":"",
  "category": "",
  "keywords": ""
}  

{ 
  "event": "viewItem",
  "item": "#Product Id#",
  "timestamp":""
}

{ 
  "event": "addToCart",
  "timestamp":"",
  "currency": "",
  "item": [
    {
      "id": "##Product Id##", 
      "price": "##Price##", 
      "quantity": "##Quantity##" 
    }
  ]
}

{ 
  "event": "viewBasket",
  "timestamp":"",
  "currency": "",
  "item": [
    {
      "id": "##Product Id 1##", 
      "price": "##Price##", 
      "quantity": "##Quantity##" 
    },
    {
      "id": "##Product Id 2##", 
      "price": "##Price##", 
      "quantity": "##Quantity##" 
    }
  ]
}

{
  "event":"beginCheckout",
  "timestamp":"",
  "currency": "",
  "item":[
    {
      "id":"#Product ID#",
      "price":"#unit price#",
      "quantity": "#quantity#"
    }
  ]
}

{
  "event": "addPaymentInfo",
  "timestamp":""
}

{
  "event":"trackTransaction",
  "timestamp":"",
  "id":"",
  "dd": "",
  "currency": "",
  "item":[
    {
      "id":"#Product ID#",
      "price":"#unit price#",
      "quantity": "#quantity#"
    }
  ]
}

Travel Specific Events:¶

{
  "event":"viewSearch",
  "timestamp":"",
  "checkin_date": "",
  "checkout_date": "",
  "nbra": "",
  "nbrc": "",
  "nbri": "",
  "nbrr": "",
}

Store Specific Events:¶

{
  "event":"viewStore",
  "timestamp":"",
  "store_id": ""
}

{
  "event":"checkAvailability",
  "timestamp":"",
  "store_id": [],
  "item": ""
}

{ 
  "event": "reserveInStore",
  "timestamp":"",
  "store_id": "",
  "currency": "",
  "item": [ 
    { 
      "id": "", 
      "quantity": "", 
      "price": "" 
    }
  ]
} 

{ 
  "event": "trackTransaction",
  "timestamp":"",
  "id": "", 
  "delivery": "store", 
  "store_id": "",
  "currency": "",
  "item": [  
    { 
      "id": "", 
      "quantity": "", 
      "price": "" }                                            
  ]
}

{ 
  "event": "trackTransaction",
  "timestamp":"",
  "id": "", 
  "user_segment": 19,
  "store_id": "",
  "currency": "",
  "item": [  
    { 
      "id": "", 
      "quantity": "", 
      "price": "" }                                            
  ]
}

Troubleshooting Responses¶

The widget call will always return a 200 response. You will need to reference the payload or lack there of to determine if the call was successful or not.

With successful responses, you will receive the response below:

{
    "errors": [],
    "warnings": []
}

If you receive errors in the response or an empty response, there is possibly an issue with the format of the data payload in the request.

It's possible you will receive a UserIdentifierMissing error like the one below. This error signifies that the email identifier is either being passed improperly or is missing.

To address this, please confirm that exactly 1 of the 4 required identifiers are getting passed through in the id node of the payload. Ensure that email is passed through the alternate_ids array if it is passed in addition to another identifier. If everything is getting sent correctly, disregard this message as it will be returned for events without email provided through alternate_ids in addition to an identifier provided in id. Sending email is not mandatory for a successfully recorded event and the message can be ignored when another valid identifier is provided.

Please refer to the examples below for more detail on identifier formatting.

{
    "errors": [
        "UserIdentifierMissing"
    ],
    "warnings": []
}

When passing a hashed email together with another type of identifier make sure hashed email is passed in a hash in the alternate_ids array and not in the id node to ensure proper user-event association.

{
  "account": "{{Criteo Account ID}}",
  "ip": "{{User IP}}",
  "id": {
    "mapping_key": "{{GUM Mapping Key}}",
    "mapped_user_id": "{{GUM Mapped User ID}}",
    
    "email": {
      "sha256": "97817c0c49994eb500ad0a5e7e2d8aed51977b26424d508f66e4e8887746a152"
    }
    
  },
  
  "alternate_ids": [
    {
      "type": "email",
      "hash_method": "sha256",
      "value": "97817c0c49994eb500ad0a5e7e2d8aed51977b26424d508f66e4e8887746a152"
    }
  ]
  
  "events":[
    {
      "event": "viewPage",
      "timestamp":"1663958019"
    }
  ],
  "version":"s2s_v1.0.0"
}

If hashed email is available for an event, but mapped_user_id is not available, be sure to pass in hashed email as the primary identifier for the event by including it in the id node instead of the alternate_ids node. Passing through an empty or undefined mapped_user_id with a hashed email in the alternate_ids node will result in the event being associated to a nonexistent user.

{
  "account": "{{Criteo Account ID}}",
  "ip": "{{User IP}}",
  "id": {
    
    "mapping_key": "{{GUM Mapping Key}}",
    "mapped_user_id": "",  //empty string or undefined
    
    
    "email": {
      "sha256": "97817c0c49994eb500ad0a5e7e2d8aed51977b26424d508f66e4e8887746a152"
    }
    
  },
  
  "alternate_ids": [
    {
      "type": "email",
      "hash_method": "sha256",
      "value": "97817c0c49994eb500ad0a5e7e2d8aed51977b26424d508f66e4e8887746a152"
    }
  ]
  
  "events":[
    {
      "event": "viewPage",
      "timestamp":"1663958019"
    }
  ],
  "version":"s2s_v1.0.0"
}

GDPR Consent¶

With our S2S solution, we give partners the ability to pass us GDPR consent through the GUM call or Event call. If you pass the GDPR consent through the GUM call, you do not need to pass it in the event call.

Passing the consent in the GUM call¶

If you send the below two additional query params in the GUM call and the user has consented to Criteo tracking, we will return a GUM ID so the event can be recorded on the Criteo side. If the user has not consented to Criteo tracking, you will not receive a UID in the response. If you use this method, it is not required to send the GDPR query parameters in the event calls. If no UID is returned in this GUM call, we will still want the event but you can send the event without a UID.

The two query parameters are below:

A sample GUM call with the above query params looks like the below: https://gum.criteo.com/sync?c={{S2S ID}}&a=1&r=2&j=_handleGumResponse&gdpr=1&gdpr_consent=CO_7cUEO_7cUEAGABCENBICgAAAAAAAAAAYgAAAAAAAA.YAAAAAAAAAAA

Passing the consent in the Event call (widget call)¶

If you choose to pass GDPR consent in the event call, you will need to add 3 query parameters to the widget endpoint. If the user has not consented to Criteo tracking, the event will be sent anonymously without the user's UID. If no UID was returned in the GUM call, you can still send the event without a UID. These query parameters are described below:

A sample widget.criteo.com (event) url for a POST or GET call with the above query params looks like the below (excluding the POST payload and GET data query parameter): https://widget.criteo.com/m/event?version=s2s_v0&gra=1&grs=CO_7cUEO_7cUEAGABCENBICgAAAAAAAAAAYgAAAAAAAA.YAAAAAAAAAAA&grv=2