Criteo Events API
Server-side event delivery to Criteo's Events API (S2S v0) for retargeting. Sending from the server avoids browser limitations and gives Criteo consistent user matching for ad optimization.
Criteo Events API is a server destination in the walkerOS flow:
Sends events server-side to Criteo using raw HTTP (no SDK). Authentication is in-payload (`account` = Partner ID, `id.mapping_key` = Caller ID). Emails are hashed into MD5, SHA-256, and SHA-256(MD5) before sending.
Installation
npm install @walkeros/collector @walkeros/server-destination-criteo- Integrated
- Bundled
import { startFlow } from '@walkeros/collector';
import destinationCriteo from '@walkeros/server-destination-criteo';
await startFlow({
destinations: {
criteo: {
code: destinationCriteo,
config: {
settings: {
partnerId: '12345',
callerId: 'CALLER_ID',
},
},
},
},
});
A complete flow.json with this destination:
{
"version": 4,
"flows": {
"default": {
"config": {
"platform": "server"
},
"destinations": {
"criteo": {
"package": "@walkeros/server-destination-criteo",
"config": {
"settings": {
"partnerId": "12345",
"callerId": "CALLER_ID"
}
}
}
}
}
}
}Configuration
This destination uses the standard destination config wrapper (consent, data, env, id, ...). For the shared fields see destination configuration. Package-specific fields live under config.settings and are listed below.
Settings
| Property | Type | Description | More |
|---|---|---|---|
partnerId | string | Criteo Partner ID (numeric string, provided by Criteo) | |
callerId | string | Caller ID for user mapping (provided by Criteo) | |
siteType | 'd' | 'm' | 't' | Site type: d (desktop), m (mobile web), t (tablet) | |
country | string | ISO 3166-1 alpha-2 country code | |
language | string | 2-letter language code | |
url | string | Custom Events API endpoint (default https://widget.criteo.com/m/event?version=s2s_v0) | |
user_data | Record<string, string> | Mapping for identity fields | |
ip | any | boolean | Client IP, sent as ip. Resolves against { ingest, event }. Default: ["ingest.ip", "event.user.ip"]. false switches it off. A mapped user_data.ip wins. | |
userAgent | any | boolean | Client user agent, sent as useragent. Resolves against { ingest, event }. Default: ["ingest.userAgent", "event.user.userAgent"]. false switches it off. A mapped user_data.useragent wins. |
Mapping
This package does not define custom rule-level settings. For the standard rule fields (consent, condition, data, batch, name, policy) see mapping.
Examples
Add to cart
A product add becomes a Criteo addToCart event with the item id, price, and quantity.
{
"name": "product add",
"data": {
"id": "SKU-B2",
"name": "Running Shoes",
"price": 89.99
},
"context": {
"shopping": [
"intent",
0
]
},
"globals": {
"pagegroup": "shop"
},
"custom": {
"completely": "random"
},
"user": {
"id": "us3r",
"device": "c00k13",
"session": "s3ss10n"
},
"nested": [
{
"entity": "product",
"data": {
"id": "SKU-B2",
"name": "Running Shoes",
"price": 89.99,
"quantity": 1
}
}
],
"consent": {
"functional": true
},
"id": "83e860384d50953f",
"trigger": "click",
"entity": "product",
"action": "add",
"timestamp": 1700000901000,
"timing": 3.14,
"source": {
"count": 1,
"trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
"type": "browser",
"platform": "web",
"url": "https://shop.example.com/products/running-shoes"
}
}{
"name": "addToCart",
"data": {
"map": {
"item": {
"loop": [
"nested",
{
"condition": {
"$code": "e=>\"object\"==typeof e&&null!==e&&\"entity\"in e&&\"product\"===e.entity"
},
"map": {
"id": "data.id",
"price": "data.price",
"quantity": {
"key": "data.quantity",
"value": 1
}
}
}
]
}
}
}
}sendServer("https://widget.criteo.com/m/event?version=s2s_v0", "{\"version\":\"walkeros_criteo_1.0.0\",\"site_type\":\"d\",\"account\":\"PARTNER_ID\",\"id\":{\"mapping_key\":\"CALLER_ID\"},\"events\":[{\"event\":\"addToCart\",\"timestamp\":\"2023-11-14T22:28:21.000Z\",\"item\":[{\"id\":\"SKU-B2\",\"price\":89.99,\"quantity\":1}]}],\"full_url\":\"https://shop.example.com/products/running-shoes\"}")Page view
A page view becomes a Criteo viewHome event used for home page impression tracking.
{
"name": "page view",
"data": {
"domain": "www.example.com",
"title": "walkerOS documentation",
"referrer": "https://www.walkeros.io/",
"search": "?foo=bar",
"hash": "#hash",
"id": "/docs/"
},
"context": {
"dev": [
"test",
1
]
},
"globals": {
"pagegroup": "docs"
},
"custom": {
"completely": "random"
},
"user": {
"id": "us3r",
"device": "c00k13",
"session": "s3ss10n"
},
"nested": [
{
"entity": "child",
"data": {
"is": "subordinated"
}
}
],
"consent": {
"functional": true
},
"id": "f0cc5f6fec3d8eeb",
"trigger": "load",
"entity": "page",
"action": "view",
"timestamp": 1700000903000,
"timing": 3.14,
"source": {
"count": 1,
"trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
"type": "browser",
"platform": "web",
"url": "https://example.com/"
}
}{
"name": "viewHome"
}sendServer("https://widget.criteo.com/m/event?version=s2s_v0", "{\"version\":\"walkeros_criteo_1.0.0\",\"site_type\":\"d\",\"account\":\"PARTNER_ID\",\"id\":{\"mapping_key\":\"CALLER_ID\"},\"events\":[{\"event\":\"viewHome\",\"timestamp\":\"2023-11-14T22:28:23.000Z\"}],\"full_url\":\"https://example.com/\"}")Purchase
A completed order is posted to the Criteo Events API as a trackTransaction event with items.
{
"name": "order complete",
"data": {
"id": "ORD-300",
"value": 249.99,
"currency": "EUR"
},
"context": {
"shopping": [
"complete",
0
]
},
"globals": {
"pagegroup": "shop"
},
"custom": {
"completely": "random"
},
"user": {
"id": "user-123",
"device": "device-456"
},
"nested": [
{
"entity": "product",
"data": {
"id": "SKU-A1",
"name": "Widget Pro",
"price": 124.99,
"quantity": 2
}
}
],
"consent": {
"functional": true
},
"id": "235d0d7bd7a213f2",
"trigger": "load",
"entity": "order",
"action": "complete",
"timestamp": 1700000900000,
"timing": 3.14,
"source": {
"count": 1,
"trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
"type": "browser",
"platform": "web",
"url": "https://shop.example.com/checkout/complete",
"referrer": "https://shop.example.com/cart"
}
}{
"name": "trackTransaction",
"data": {
"map": {
"id": "data.id",
"item": {
"loop": [
"nested",
{
"condition": {
"$code": "e=>\"object\"==typeof e&&null!==e&&\"entity\"in e&&\"product\"===e.entity"
},
"map": {
"id": "data.id",
"price": "data.price",
"quantity": {
"key": "data.quantity",
"value": 1
}
}
}
]
}
}
}
}sendServer("https://widget.criteo.com/m/event?version=s2s_v0", "{\"version\":\"walkeros_criteo_1.0.0\",\"site_type\":\"d\",\"account\":\"PARTNER_ID\",\"id\":{\"mapping_key\":\"CALLER_ID\"},\"events\":[{\"event\":\"trackTransaction\",\"timestamp\":\"2023-11-14T22:28:20.000Z\",\"id\":\"ORD-300\",\"item\":[{\"id\":\"SKU-A1\",\"price\":124.99,\"quantity\":2}]}],\"full_url\":\"https://shop.example.com/checkout/complete\",\"previous_url\":\"https://shop.example.com/cart\"}")View item
A product view becomes a Criteo viewItem event with the viewed product id.
{
"name": "product view",
"data": {
"id": "SKU-C3",
"name": "Coffee Maker"
},
"context": {
"shopping": [
"detail",
0
]
},
"globals": {
"pagegroup": "shop"
},
"custom": {
"completely": "random"
},
"user": {
"id": "us3r",
"device": "c00k13",
"session": "s3ss10n"
},
"nested": [
{
"entity": "product",
"data": {
"id": "SKU-C3"
}
}
],
"consent": {
"functional": true
},
"id": "db22fb16c70f663d",
"trigger": "load",
"entity": "product",
"action": "view",
"timestamp": 1700000902000,
"timing": 3.14,
"source": {
"count": 1,
"trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
"type": "browser",
"platform": "web",
"url": "https://shop.example.com/products/coffee-maker"
}
}{
"name": "viewItem",
"data": {
"map": {
"item": {
"loop": [
"nested",
{
"condition": {
"$code": "e=>\"object\"==typeof e&&null!==e&&\"entity\"in e&&\"product\"===e.entity"
},
"map": {
"id": "data.id"
}
}
]
}
}
}
}sendServer("https://widget.criteo.com/m/event?version=s2s_v0", "{\"version\":\"walkeros_criteo_1.0.0\",\"site_type\":\"d\",\"account\":\"PARTNER_ID\",\"id\":{\"mapping_key\":\"CALLER_ID\"},\"events\":[{\"event\":\"viewItem\",\"timestamp\":\"2023-11-14T22:28:22.000Z\",\"item\":[{\"id\":\"SKU-C3\"}]}],\"full_url\":\"https://shop.example.com/products/coffee-maker\"}")Failures
A response outside the 2xx range, a network error, or no answer within 5 seconds fails the event: the push answers failed with the code transport (with the HTTP status) or timeout, the event goes to the dead-letter queue, and the collector logs one ERROR line. Any 2xx answer counts as delivered: the destination does not read the response body. Without partnerId or callerId the destination does not start: every push answers failed with the code config, and the collector logs destination init failed. A rule with silent: true sends nothing.
Client IP and user agent
The destination sends the client IP as ip and the user agent as useragent by default. The ip and userAgent settings resolve against { ingest, event } and default to ["ingest.ip", "event.user.ip"] and ["ingest.userAgent", "event.user.userAgent"], so they fill in whenever the source provides them (see the config.ingest recipe on the Express source). A value that user_data in settings maps to ip or useragent wins; a rule's data is not read for them. A value that resolves to nothing is not sent. Set either setting to false to turn it off, or to another mapping value to read it elsewhere.
Consent
The quickstart sets no config.consent, so Criteo receives every event, whatever consent the event carries. To send only events with consent, add consent: { marketing: true } to config, next to settings (with several keys listed, one granted key is enough). An event without that consent is skipped or queued, depending on the collector's consentDenied. Server flows built by the CLI skip it and count it in skipped. With startFlow it waits in the destination's queue by default: a later event that carries consent does not release it, and only a walker consent command does, which then sends the waiting events of every user at once. Pass consentDenied: 'skip' to startFlow to skip such events instead (see Gate a destination with consent and consent-denied events on a server).
Event mapping
Criteo uses its own standard event names. Set the Criteo event name via each rule's name field.
| walkerOS Event | Criteo Event Name |
|---|---|
page view | viewHome / viewPage |
product view | viewItem |
product list | viewList |
product add | addToCart |
cart view | viewBasket |
checkout start | beginCheckout |
checkout payment | addPaymentInfo |
order complete | trackTransaction |
user login | login |
An event without a rule name is sent under its walkerOS name, such as page view, which is not a Criteo event name.
"mapping": {
"order": {
"complete": {
"name": "trackTransaction",
"data": {
"map": {
"id": "data.id",
"item": {
"loop": [
"nested",
{
"map": {
"id": "data.id",
"price": "data.price",
"quantity": "data.quantity"
}
}
]
}
}
}
}
}
}User identity
Criteo matches users via three signals. Wire them through user_data in settings. Only these three keys are read there (besides ip and useragent), each as one value:
| Field | Description |
|---|---|
mapped_user_id | Criteo GUM ID |
email | Raw email. Hashed into MD5, SHA-256 and SHA-256(MD5) |
retailer_visitor_id | Stable retailer visitor identifier |
Any other key, a list, and a user_data object in a rule's data are dropped without a log line.
"settings": {
"partnerId": "12345",
"callerId": "YOUR_CALLER_ID",
"user_data": {
"mapped_user_id": "user.id",
"email": "user.email",
"retailer_visitor_id": "user.device"
}
}Email hashing
Raw emails are lowercased and trimmed, then hashed into all three formats Criteo expects:
md5: MD5 hex digestsha256: SHA-256 hex digestsha256_md5: SHA-256 hex of the MD5 hex string
A value that is already a hash is not hashed again: a 64-character hex value is sent as sha256 only, and a 32-character hex value is sent as md5, with sha256_md5 derived from it.
Deduplication
Criteo Events API supports deduplication with Criteo OneTag by sharing a deduplication_page_view_id across channels. Wire it via data.map.deduplication_page_view_id in the event mapping.