Criteo OneTag Pixel Setup and Conversion Tracking | OpsBlu Docs

Criteo OneTag Pixel Setup and Conversion Tracking

Technical guide to Criteo OneTag deployment, product-level event tracking, Dynamic Retargeting setup, and Events API integration.

How Criteo Tracking Works

Criteo tracking centers on the OneTag, a JavaScript snippet that loads static.criteo.net/js/ld/ld.js and fires structured events back to Criteo's servers. The OneTag identifies users through a combination of hashed email addresses, Criteo's own cross-device identity graph, and first-party cookies stored under the criteo domain.

When the OneTag loads, it:

  1. Reads the cto_bundle first-party cookie (or sets one if absent) containing the Criteo user identifier
  2. Sends the current page context (URL, referrer, device type) to sslwidget.criteo.com
  3. Matches the user against Criteo's Shopper Graph for cross-device resolution
  4. Fires any queued events (page view, product view, cart, transaction) to dis.criteo.com

All product-level events require a Partner ID (your Criteo account number) and use a structured criteo_q array to batch multiple events per page load.

Data flows from the OneTag to Criteo's real-time bidding engine, which uses product catalog data (via your product feed) to assemble dynamic ad creatives within milliseconds of a bid request.

Installing the Criteo OneTag

Place the OneTag loader on every page, typically in the <head> or just before </body>:

<script type="text/javascript" src="//static.criteo.net/js/ld/ld.js" async="true"></script>
<script type="text/javascript">
window.criteo_q = window.criteo_q || [];
window.criteo_q.push(
  { event: "setAccount", account: 12345 },       // Your Partner ID
  { event: "setSiteType", type: "d" },            // d=desktop, m=mobile, t=tablet
  { event: "setEmail", email: "", hash_method: "sha256" }  // Hashed email if available
);
</script>

The setSiteType event must fire on every page. Criteo uses it to select the correct creative dimensions for dynamic ads.

For Single Page Applications, re-fire the criteo_q array on each virtual page navigation. The loader script only needs to be included once.

Conversion Tracking

Criteo uses four core events for the ecommerce funnel. Each event pushes to the criteo_q array.

Homepage Visit

<script type="text/javascript">
window.criteo_q = window.criteo_q || [];
window.criteo_q.push(
  { event: "setAccount", account: 12345 },
  { event: "setSiteType", type: "d" },
  { event: "viewHome" }
);
</script>

Product View

<script type="text/javascript">
window.criteo_q = window.criteo_q || [];
window.criteo_q.push(
  { event: "setAccount", account: 12345 },
  { event: "setSiteType", type: "d" },
  { event: "viewItem", item: "PRODUCT-SKU-123" }
);
</script>

Category / Listing Page

<script type="text/javascript">
window.criteo_q = window.criteo_q || [];
window.criteo_q.push(
  { event: "setAccount", account: 12345 },
  { event: "setSiteType", type: "d" },
  { event: "viewList", item: ["SKU-001", "SKU-002", "SKU-003"] }
);
</script>

Add to Cart

<script type="text/javascript">
window.criteo_q = window.criteo_q || [];
window.criteo_q.push(
  { event: "setAccount", account: 12345 },
  { event: "setSiteType", type: "d" },
  { event: "addToCart", item: [
    { id: "SKU-001", price: 49.99, quantity: 1 },
    { id: "SKU-002", price: 29.99, quantity: 2 }
  ]}
);
</script>

Transaction (Purchase)

<script type="text/javascript">
window.criteo_q = window.criteo_q || [];
window.criteo_q.push(
  { event: "setAccount", account: 12345 },
  { event: "setSiteType", type: "d" },
  { event: "trackTransaction", id: "ORDER-789", item: [
    { id: "SKU-001", price: 49.99, quantity: 1 },
    { id: "SKU-002", price: 29.99, quantity: 2 }
  ]}
);
</script>

The id field in trackTransaction must match a unique order ID. Criteo deduplicates transactions on this value within a 24-hour window.

Dynamic Retargeting and Audience Building

Criteo's Dynamic Retargeting assembles personalized product ads by matching user browsing behavior against your product feed. The system requires:

  1. Product feed -- An XML or CSV feed uploaded to Criteo Management Center or served via URL. Must include id, title, description, link, image_link, price, availability, and gtin or mpn fields. Product IDs in the feed must exactly match the IDs passed in OneTag events.

  2. OneTag events -- The viewItem, addToCart, and trackTransaction events provide the behavioral signal. Criteo's engine scores users based on recency and depth of engagement (viewed only vs. added to cart vs. purchased).

  3. Creative templates -- Configured in Criteo Management Center. The engine selects products, layout, and CTA dynamically per impression.

Audience segments Criteo builds automatically include:

  • Viewers -- Users who viewed products but did not add to cart
  • Cart Abandoners -- Users who added products but did not purchase
  • Buyers -- Users who completed a transaction (used for cross-sell/upsell or suppression)
  • Lapsed Buyers -- Purchasers who have not returned within a configurable window

You can configure exclusion windows (e.g., suppress ads to buyers for 30 days) and frequency caps in the Criteo Management Center.

Server-Side / Events API Integration

The Criteo Events API allows server-side event ingestion, bypassing browser-based tracking limitations from ad blockers or ITP restrictions.

Sending a Conversion Event

curl -X POST "https://sslwidget.criteo.com/event" \
  -H "Content-Type: application/json" \
  -d '{
    "account": 12345,
    "site_type": "d",
    "email": "sha256_hashed_email_here",
    "events": [
      {
        "event": "trackTransaction",
        "id": "ORDER-789",
        "item": [
          { "id": "SKU-001", "price": 49.99, "quantity": 1 }
        ]
      }
    ]
  }'

Catalog API (Product Feed)

For large catalogs with frequent inventory changes, the Criteo Retail Media API supports programmatic feed updates:

curl -X POST "https://api.criteo.com/2024-01/retail-media/catalog/products" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "type": "RetailMediaCatalogProduct",
      "attributes": {
        "productId": "SKU-001",
        "name": "Running Shoes",
        "price": 49.99,
        "availability": "InStock",
        "imageUrl": "https://example.com/images/sku-001.jpg",
        "productUrl": "https://example.com/products/sku-001"
      }
    }
  }'

Authentication uses OAuth 2.0 client credentials flow against https://api.criteo.com/oauth2/token.

Common Issues

Product ID Mismatch Between Feed and OneTag

The most frequent integration failure. If the id passed in viewItem or trackTransaction does not exactly match a productId in the feed (including case and whitespace), Criteo cannot build dynamic creatives for that product. Validate with:

// Debug: log all product IDs being sent
window.criteo_q.forEach(function(evt) {
  if (evt.event === "viewItem" || evt.event === "trackTransaction") {
    console.log("Criteo product ID:", evt.item || evt.id);
  }
});

OneTag Not Firing on SPAs

The OneTag loader only initializes once. On client-side route changes, you must manually re-push events to criteo_q. In React:

useEffect(() => {
  window.criteo_q = window.criteo_q || [];
  window.criteo_q.push(
    { event: "setAccount", account: 12345 },
    { event: "setSiteType", type: getDeviceType() },
    { event: "viewItem", item: productId }
  );
}, [productId]);

Duplicate Transactions

If the order confirmation page reloads or the user navigates back, the trackTransaction event fires twice. Criteo deduplicates on the id field within 24 hours, but only if the ID is consistent. Use a stable order ID, not a random value generated on each page load.

Safari's Intelligent Tracking Prevention caps third-party cookie lifetimes. The cto_bundle cookie set by criteo.com may be purged after 7 days of no interaction. Mitigate by passing hashed email via setEmail on every page load when available -- this enables server-side identity resolution independent of cookies.

Network Requests Blocked by Ad Blockers

Requests to static.criteo.net and dis.criteo.com are blocked by most ad blocker filter lists. Server-side Events API integration is the primary mitigation path. There is no reliable client-side workaround.

Platform-Specific Considerations

Product Feed Requirements -- Criteo enforces strict feed validation. Feeds with more than 5% errors (missing required fields, invalid URLs, price format issues) may be rejected entirely. The feed must be refreshed at least daily; stale pricing or out-of-stock items in dynamic ads create poor user experience and can trigger Criteo account review.

Criteo Shopper Graph -- Unlike cookie-only identity systems, Criteo maintains a deterministic identity graph built from hashed email, device fingerprints, and login events across its publisher network. Passing setEmail with a SHA-256 hashed email on every page dramatically improves match rates and cross-device attribution accuracy.

Commerce Media Platform -- Criteo's newer Retail Media offering allows brands to run sponsored product ads within retailer websites (similar to Amazon Sponsored Products). This uses a separate API and campaign management interface from standard Dynamic Retargeting, though the product feed can be shared.

Bid Optimization -- Criteo uses a proprietary ML model for bid optimization that is not directly configurable. You set CPC or COS (Cost of Sale) targets, and the algorithm adjusts bids per impression. Performance tuning is primarily done through audience exclusions, product feed quality, and target adjustments rather than manual bid overrides.

Data Retention -- Criteo retains user-level behavioral data for 13 months. Event data for reporting purposes is available for 25 months. Transaction-level data can be exported via the Management Center or API.

Back to top