Skip to main content
Ask your AI

Criteo Events API

Server Source code Package Beta

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.

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/collector @walkeros/server-destination-criteo
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',
        },
      },
    },
  },
});

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​

PropertyTypeDescriptionMore
partnerId*stringCriteo Partner ID (numeric string, provided by Criteo)
callerId*stringCaller ID for user mapping (provided by Criteo)
siteType'd' | 'm' | 't'Site type: d (desktop), m (mobile web), t (tablet)
countrystringISO 3166-1 alpha-2 country code
languagestring2-letter language code
urlstringCustom Events API endpoint (default https://widget.criteo.com/m/event?version=s2s_v0)
user_dataRecord<string, string>Mapping for identity fields
ipany | booleanClient IP, sent as ip. Resolves against { ingest, event }. Default: ["ingest.ip", "event.user.ip"]. false switches it off. A mapped user_data.ip wins.
userAgentany | booleanClient 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.
* 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": "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"
  }
}
Mapping
{
  "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
              }
            }
          }
        ]
      }
    }
  }
}
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": "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/"
  }
}
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",
    "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"
  }
}
Mapping
{
  "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
              }
            }
          }
        ]
      }
    }
  }
}
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": "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"
  }
}
Mapping
{
  "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"
            }
          }
        ]
      }
    }
  }
}
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\"}")

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.

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 EventCriteo Event Name
page viewviewHome / viewPage
product viewviewItem
product listviewList
product addaddToCart
cart viewviewBasket
checkout startbeginCheckout
checkout paymentaddPaymentInfo
order completetrackTransaction
user loginlogin

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:

FieldDescription
mapped_user_idCriteo GUM ID
emailRaw email. Hashed into MD5, SHA-256 and SHA-256(MD5)
retailer_visitor_idStable 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 digest
  • sha256: SHA-256 hex digest
  • sha256_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.

💡 Need implementation support?
elbwalker offers hands-on support: setup review, measurement planning, destination mapping, and live troubleshooting. Book a 2-hour session (€399)