Criteo Events API

Server Source code Package Beta

Server-side event delivery to Criteo's Events API (S2S v0) for reliable retargeting, bypassing browser limitations and providing consistent user matching for ad optimization.

Where this fits

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/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: 'YOUR_PARTNER_ID',
        callerId: 'YOUR_CALLER_ID',
      },
    },
  },
},
});

Add to your flow.json destinations:

"destinations": {
"criteo": {
  "package": "@walkeros/server-destination-criteo",
  "import": "destinationCriteo",
  "config": {
    "settings": {
      "partnerId": "YOUR_PARTNER_ID",
      "callerId": "YOUR_CALLER_ID"
    }
  }
}
}

See bundled mode setup | CLI reference

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
`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

* Required fields

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.

Event

{
  "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": "54290bc5baa6bbba",
  "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"
  }
}

Mapping

{
  "name": "addToCart",
  "data": {
    "map": {
      "item": {
        "loop": [
          "nested",
          {
            "condition": {
              "$code": "e=>w(e)&&\"product\"===e.entity"
            },
            "map": {
              "id": "data.id",
              "price": "data.price",
              "quantity": {
                "key": "data.quantity",
                "value": 1
              }
            }
          }
        ]
      }
    }
  }
}

Out

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.

Event

{
  "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": "8bfacc59062c3806",
  "trigger": "load",
  "entity": "page",
  "action": "view",
  "timestamp": 1700000903000,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "browser",
    "platform": "web",
    "url": "https://example.com/"
  }
}

Mapping

{
  "name": "viewHome"
}

Out

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.

Event

{
  "name": "order complete",
  "data": {
    "id": "ORD-300",
    "total": 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": "bcd3ecb191288fab",
  "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"
  }
}

Mapping

{
  "name": "trackTransaction",
  "data": {
    "map": {
      "id": "data.id",
      "item": {
        "loop": [
          "nested",
          {
            "condition": {
              "$code": "e=>w(e)&&\"product\"===e.entity"
            },
            "map": {
              "id": "data.id",
              "price": "data.price",
              "quantity": {
                "key": "data.quantity",
                "value": 1
              }
            }
          }
        ]
      }
    }
  }
}

Out

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.

Event

{
  "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": "51a4aaf76873cea1",
  "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"
  }
}

Mapping

{
  "name": "viewItem",
  "data": {
    "map": {
      "item": {
        "loop": [
          "nested",
          {
            "condition": {
              "$code": "e=>w(e)&&\"product\"===e.entity"
            },
            "map": {
              "id": "data.id"
            }
          }
        ]
      }
    }
  }
}

Out

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\"}")

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`

"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:

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

"settings": {
"partnerId": "YOUR_PARTNER_ID",
"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 digest
sha256: SHA-256 hex digest
sha256_md5: SHA-256 hex of the MD5 hex string

Pre-hashed values (detected by hex length: 32 chars for MD5, 64 for SHA-256) are passed through without re-hashing.

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.

Installation​

Configuration​

Settings​

Mapping​

Examples

Add to cart

Page view

Purchase

View item

Event mapping​

User identity​

Email hashing​

Deduplication​

Links​

Installation

Configuration

Settings

Mapping

Event mapping

User identity

Email hashing

Deduplication

Links