Introduction

BeaconSDK is Criteo’s lightweight external JavaScript library that automates beacon tracking on web. It handles the entire beacon lifecycle (load, view, and click) so you don’t have to build or maintain a custom tracking logic. The result is faster integrations, cleaner data, and consistent measurement across all placements and products.

Process overview integrating with the BeaconSDK

For more information on the different levels of beacons, please check the ad tracking introduction page.

Quick Start

Criteo’s Delivery API returns unique beacon URLs for each placement and product (SKU). To start tracking with BeaconSDK using the new static JavaScript bundle, follow these steps:

Add Beacon Attributes to your HTML tags

Each beacon URL returned by the Delivery API response must be attached to the corresponding HTML element using a data- attribute in the format data-criteo-[beacon-level]-[beacon-type]

<!-- Product Placement -->
<div class="sponsored-product-placement carousel"
  data-criteo-placement-onloadbeacon="//b.criteo.com/rm?rm_e=4cp0JZowKy"
  data-criteo-placement-onviewbeacon="//b.criteo.com/rm?rm_e=rM9TNBqBpz"
  data-criteo-placement-onclickbeacon="//b.criteo.com/rm?rm_e=JdnOdb4Ns8"
>
  <!-- Product Tile -->
  <div class="sponsored-product-tile"
    data-criteo-product-onloadbeacon="//b.criteo.com/rm?rm_e=q5CjxkuM0B"
    data-criteo-product-onviewbeacon="//b.criteo.com/rm?rm_e=04im9RY12L"
  >

    <!-- onClick beacon on link to product page -->
    <a href="https://www.example.com/product-page"
      data-criteo-product-onclickbeacon="//b.criteo.com/rm?rm_e=9dUq1vC2Ns">
      <div class="img">
        <img class="product-img" 
          src="https://www.example.com/product-img.webp">
      </div>
      <div class="product-name">
        Product Example Name 
      </div>
    </a>

    <div class="actions">
      <!-- onBasketChange beacon on add-to-cart button -->
      <button class="btn add-to-cart" 
        data-criteo-product-onbasketchangebeacon="//b.criteo.com/rm?rm_e=J7fX1vL3Qz">
        <i class="icon">add_to_cart_icon</i>
      </button>
      <!-- onWishlist beacon on Favorite (e.g. heart) button -->
      <button class="wishlist-btn" 
        data-criteo-product-onwishlistbeacon="//b.criteo.com/rm?rm_e=W8gY2vD4Rt">
        <i class="icon">favorite_icon</i>
      </button>
    </div>

  </div>
</div>

[beacon-level] is one of product or placement, and [beacon-type] is one of onloadbeacon, onviewbeacon, onclickbeacon, onbasketchangebeacon, and onwishlistbeacon.

Page Intelligence placements

Placements returned from the Page Intelligence /optimize endpoint use a StructuredBeacon object for onLoadBeacon instead of a plain URL string. To pass the payload to BeaconSDK, set data-criteo-placement-onloadbeacon to the url value and add one data-criteo-placement-onloadbeacon-payload-[key] attribute per entry in the payload object:

<div class="page-intelligence-placement"
  data-criteo-placement-onloadbeacon="//b.criteo.com/rm?u=1&ev=4"
  data-criteo-placement-onloadbeacon-payload-rm_e="4cp0JZowKy"
  data-criteo-placement-onloadbeacon-payload-sku="6887100|6887924"
  data-criteo-placement-onloadbeacon-payload-slot="0|1"
  data-criteo-placement-onloadbeacon-payload-ex="5454644"
  data-criteo-placement-onloadbeacon-payload-st="organic"
  data-criteo-placement-onviewbeacon="//b.criteo.com/rm?rm_e=rM9TNBqBpz"
>
  ...
</div>

When data-criteo-placement-onloadbeacon-payload-* attributes are present, BeaconSDK fires the beacon using navigator.sendBeacon(url, data) where data is the application/x-www-form-urlencoded string of all payload parameters.

The data-criteo-placement-onloadbeacon-payload-* attributes apply only to placements from the /optimize endpoint. For placements from the Delivery API, use the standard data-criteo-placement-onloadbeacon attribute with the plain URL.

Load BeaconSDK

At the end of your HTML document, before the closing the <body> tag, include the BeaconSDK bundle using the script tag:

<script src="https://static.criteo.net/cbs/prod/stable/BeaconSDK/bundle.js" data-dynamic-tracking="true" defer></script>

Implementation Examples

Below are example implementations of BeaconSDK in different scenarios.

Example 1: Basic integration

Here’s a simple example that uses only sponsored products and BeaconSDK to track OnLoad, OnView, and OnClick events. We also added a simple JavaScript function to handle add-to-cart (OnBasketChange) and add-to-wishlist (OnWishlist) beacons.

Example 2: Dynamic content (lazy loading / SPA)

When placements are dynamically injected (e.g. infinite scroll or single-page applications), enable dynamic tracking:

Example 3: Placement-level Tracking

This example shows a simplified implementation where only placement-level beacons are used.

Example 4: Video Placement

This example demonstrates how BeaconSDK can be used with video placements.

Usage

In its most basic form, BeaconSDK will automatically observe and track all HTML elements that include attributes matching the format data-criteo-[beacon-level]-[beacon-type] BeaconSDK supports the following beacon types:

OnLoadBeacon — triggered as soon as the SDK detects the HTML element, regardless of its visibility in the viewport.
OnViewBeacon — triggered when the element meets IAB’s Viewable Impression Guidelines.
OnClickBeacon, OnBasketChangeBeacon, and OnWishlistBeacon— triggered by default when the corresponding HTML element is clicked.

All beacon URLs are sent using the navigator.sendBeacon() method.

All click events (OnClickBeacon, OnBasketChangeBeacon, and OnWishlistBeacon) are tracked during the capture phase of the dispatched event. That ensure beacons will be sent even if client-side libraries use stopPropagation() in bubbling events.

Dynamic Tracking

By default, BeaconSDK will only track HTML elements that are present in the DOM at the time the script is loaded. To enable dynamic tracking of elements added later, use the data-dynamic-tracking="true" parameter on the script tag:

<script src="https://static.criteo.net/cbs/prod/stable/BeaconSDK/bundle.js" data-dynamic-tracking="true" defer></script>

When this parameter is enabled, BeaconSDK uses the MutationObserver API to monitor changes in the DOM and register new elements that match the data-criteo-* pattern.

Restricting Tracking to a Specific Container

By default, the SDK observes all subnodes of the <body> element. If you want to restrict the tracking to a specific container or a shadow DOM root, you can specify a container using the data-container-selector attribute:

<script src="https://static.criteo.net/cbs/prod/stable/BeaconSDK/bundle.js"
        type="text/javascript"
        data-dynamic-tracking="true"
        data-container-selector=".sponsored-products"
        defer></script>

This limits DOM observation to elements within the specified container selector.

Tracking Organic Add-to-cart Events

BeaconSDK introduced support to track organic add-to-cart (ATC) events in version 5. Because add-to-cart events are not beacons, but API calls, it requires setting up a context with the necessary information to send the event correctly. For each page load:

Load BeaconSDK
Set the organic context after the initial Delivery response
Tag the organic add-to-cart controls
(For testing purposes) Verify the addToCart GET request in Network and/or console logs.

Setting the page-level context

The context can be set either using attibutes in BeaconSDK’s <script> tag or by calling the setOrganicContext interface.

Make sure BeaconSDK is loaded before setting the context.

Required fields

endpoint — Delivery base URL (e.g. https://d.us.criteo.com/delivery/retailmedia in AMER or https://d.eu.criteo.com/delivery/retailmedia in EMEA).
partnerId — same value as criteo-partner-id.
pageId — page-id used on the initial Delivery call, e.g. viewSearchResult_API_mobile or viewSearchResultApiMobile.

Recommended fields

If these fields are omitted, BeaconSDK will through warnings to the console, but it will still set the context.

visitorId — same as retailer-visitor-id. Should only be omitted if the user opted out of tracking.
pageUid — the page-uid sent in the Delivery API response. Omitting this field will inflate the count of page views artificially.

Optional fields

customerId — same as customer-id. Should be sent if the shopper is logged in.
authToken — if you use authentication tokens on Delivery calls, set the Bearer token. BeaconSDK uses fetch() with the header Authorization: Bearer <token>. If fetch isn’t available in the client, BeaconSDK will try to fall back to an image request, but it won’t be able to send the token, and it will log a warning.

Examples

Using the setOrganicContext interface. Recommended for dynamic pages:

window.BeaconSDK.setOrganicContext({
  endpoint:    "https://d.us.criteo.com/delivery/retailmedia", // required
  partnerId:   "<criteo-partner-id>",                          // required
  visitorId:   "<retailer-visitor-id>",                        // optional
  customerId:  "<customer-id>",                                // optional
  pageId:      "<same page-id as Delivery API request>",       // required
  pageUid:     "<from the Delivery response>",                 // nice to have but optional
  environment: "d",                                            // optional
  authToken:   "<bearer-token>",                      // optional
});

Using attributes in the <script> tag. Recommended for static pages or Server-side Rendering (SSR):

<script src="https://static.criteo.net/cbs/prod/stable/BeaconSDK/bundle.js"
        type="text/javascript"
        data-dynamic-tracking="true"
        data-organic-atc="true"
        data-organic-endpoint="true"
        data-organic-partner-id="<criteo-partner-id>"
        data-organic-visitor-id="<retailer-visitor-id>"
        data-organic-customer-id="<customer-id>"
        data-organic-page-id="<same page-id as Delivery API request>"
        data-organic-page-uid="<from the Delivery response>"
        data-organic-auth-token="<bearer-token>"
        defer></script>

If required values are missing, BeaconSDK will send a warning and you should use setOrganicContext instead.

If you need to reload the organic context, for example, in Single Page Applications (SPAs), you can call window.BeaconSDK.clearOrganicContext() and then, after the next Delivery response, you can call setOrganicContext again with the new context data.

Tagging organic add-to-cart elements

Add the following attributes to the HTML element equivalent to the add-to-cart button

Required

data-criteo-organic-atc="true"
data-criteo-item="<sku id>"
data-criteo-price="<sku price>"

Optional

data-criteo-quantity="1". Defaults to 1. Should only be set if clicking on the button will add more than 1 item to the cart
data-criteo-parent-item="<parent sku id>". Set if you use parent sku ids (item_group_id) in your product feed.

Example

<button
  type="button"
  data-criteo-organic-atc="true"
  data-criteo-item="SKU-123"
  data-criteo-price="34.99"
  data-criteo-quantity="1"
  data-criteo-parent-item="P456">
  Add to cart
</button>

Do not use these attributes on sponsored products — for those, use the product beacon attributes as described in this page (e.g. data-criteo-product-onbasketchangebeacon).

What to verify

After calling setOrganicContext (or adding the script-tag organic config), clicking a tagged organic ATC button should trigger a GET request to the configured endpoint with parameters including: event-type=addToCart, page-uid, item, price, and the optionals quantity and parent-item. If you set authToken, the request should go via fetch with a header Authorization: Bearer <token>.

Debugging

BeaconSDK provides two tools to help debug your integration: a logger and a viewability visualizer.

Tracking always runs whether or not debug is enabled.

Logging beacons

To help debug beacon tracking in your browser, you can enable debug logs. This can be done through the following ways:

Adding a cookie criteo-viewability-debug=true

document.cookie = "criteo-viewability-debug=true;"

Adding the parameter data-debug="true" to the <script> tag

<script src="https://static.criteo.net/cbs/prod/stable/BeaconSDK/bundle.js" 
        data-debug="true"
        type="text/javascript"
        defer/>

Using the method enableDebug() from the BeaconSDK interface available after it is loaded

    window.BeaconSDK.enableDebug();

Once enabled, BeaconSDK will log each beacon it sends to the browser console. These logs start with the prefix Criteo: sent [beacon-level]-[beacon-type] beacon:. You can filter your browser console by the keyword Criteo to isolate these logs.

Each log entry includes an object with the following properties:

BeaconType: a string indicating the type of beacon sent
BeaconURL: the URL that was called via sendBeacon()
HTMLElement: the actual DOM element that triggered the beacon (hovering it in DevTools will highlight the element)

Criteo: sent product-onLoad beacon:

{
  "BeaconType": "product-onLoad",
  "BeaconURL": "//b.us.criteo.com/rm?rm_e=productTwoOnLoadBeacon",
  "HTMLElement": "<div class='sponsored-product-tile hoverable waves-effect'>...</div>"
}

Universal Beacons

BeaconSDK will track Universal Beacons out of the box. The only difference being that there are no product-level OnLoad beacons. When logging universal beacons to the console, BeaconSDK will show the beacon URL, the excluded SKUs, and the status codes.

Viewability visualizer

To help debug viewable impressions, i.e., OnView beacons, BeaconSDK also provides a visualizer that will show a blue check mark for the placement-level OnView beacons and a green check mark for product-level OnView beacons for 2 seconds.

The visualizer can be enabled through the following methods:

Adding the parameter data-visualizer="true" to the <script> tag

<script src="https://static.criteo.net/cbs/prod/stable/BeaconSDK/bundle.js" 
        data-visualizer="true"
        type="text/javascript" 
        defer/>

Using setting the property visualizer from the BeaconSDK interface to true, after the bundle is loaded

window.BeaconSDK.visualizer = true;

Getting BeaconSDK

We offer three options to get started with BeaconSDK.

Stable version via `<script>` tag (Recommended)

You can directly load BeaconSDK by adding the following <script> tag to your website:

<script src="https://static.criteo.net/cbs/prod/stable/BeaconSDK/bundle.js" defer></script>

You should place this script tag at the end of your <body> tag, just before the closing </body> tag. This ensures that the SDK loads after your page content. If your website dynamically loads content, see the section on Dynamic Tracking

The /stable/ endpoint will always serve the minified code of the latest (stable) release. By using this endpoint you will auto-update your bundle without having to worry about versioning.

Version-specific endpoints

If you need to lock BeaconSDK to a specific version, we also offer the following endpoints that can be used in the src parameter:

Major version

This version will include all minor-version updates automatically. These are updates that guarantee no backward compatibility breaks

Minimized bundle

<script src="https://static.criteo.net/cbs/prod/v5/BeaconSDK/bundle.min.js" defer></script>

Expanded-code bundle

<script src="https://static.criteo.net/cbs/prod/v5/BeaconSDK/bundle.js" defer></script>

Minor version

This endpoint will not change it’s content once released.

Minimized bundle

<script src="https://static.criteo.net/cbs/prod/v5.0.0/BeaconSDK/bundle.min.js" defer></script>

Expanded code bundle

<script src="https://static.criteo.net/cbs/prod/v5.0.0/BeaconSDK/bundle.js" defer></script>

OneTag Bundle

If you already use Criteo’s OneTag for Marketing Solutions or offsite campaigns, BeaconSDK can be automatically included via the OneTag bundle. Please consult your Technical Account Manager (TAM) to confirm whether your OneTag setup supports BeaconSDK and to enable it if needed.

TypeScript NPM Package

If you prefer to integrate BeaconSDK directly into your build process, you can request the latest version of the npm package from your Technical Account Manager (TAM).

This option is only recommended if you want to build the SDK as part of your project and serve it from your own infrastructure.

See installation instructions below.

Installing and Self-hosting

BeaconSDK can be provided as a compressed TypeScript package. Once transpiled, the library is compliant with both CommonJS and ES6+ environments. If you want to install and run BeaconSDK locally, ask your Technical Account Manager (TAM) for the package.

Installation

Run npm install to ensure that TypeScript is installed in your project.
Download the .tgz file received from your TAM. It will be named in the format: criteo-beacon-sdk-x.y.z.tgz (where x.y.z is the SDK version).
Move the .tgz file into your project directory.
Run:
```
1. npm install criteo-beacon-sdk-x.y.z.tgz
```
Make sure to replace x.y.z with the actual version string.

After the installation, you can import Import the necessary classes from the SDK into your JavaScript file:

import PlacementLevelBeaconHandler from '/beacon-sdk/PlacementLevelBeaconHandler.js';
import ProductLevelBeaconHandler from '/beacon-sdk/ProductLevelBeaconHandler.js';
import ViewabilityVisualizer from '[PROJECT_DIRECTORY]/debug/SkuViewabilityVisualizer'; // debug porposes only

// Attach handlers to the global window object for easy access
window.PlacementLevelBeaconHandler = PlacementLevelBeaconHandler;
window.ProductLevelBeaconHandler = ProductLevelBeaconHandler;

Use the provided functions

You can then start using the functions provided by BeaconSDK:

/* [...]
    PlacementLevelBeaconHandler.attachOnViewBeacons();
    PlacementLevelBeaconHandler.triggerOnLoadBeacons();
/* [...]

Placement-level beacon handler

The PlacementLevelBeaconHandler class provides various methods for handling placement-level beacons. These beacons track user interactions with different ad placements.

triggerOnLoadBeacons(): sends onLoad beacons for elements with the data-criteo-placement-onloadbeacon attribute. This method iterates over all elements with the specified attribute and sends a beacon for each element when the page loads.
attachOnViewBeacons(): attaches beacons to placements with the data-criteo-placement-onviewbeacon attribute. This method uses the IntersectionObserver API to monitor the visibility of ad placements and sends a beacon when an ad placement meets the viewability threshold according to IAB’s Viewable Impression Guidelines.
attachOnClickBeacons([jsEvent]): attaches onClick beacons to placements with the data-criteo-placement-onclickbeacon attribute. If a JavaScript event is not provided, the default 'click' event will be used.
triggerOnClickBeacon(beaconUrl, element): sends onClick beacons for placement-level elements. You should use this method if you want to handle the click beaconing together with other routines. It should be called with the beacon URL when a user clicks on an ad placement. An optional element parameter can be used to associate the beacon with a specific element.
triggerOnFileClickBeacon(beaconUrl, element): sends onFileClick beacons for placement-level elements. This method should be called with the beacon URL when a user clicks on a file within an ad placement. An optional element parameter can be used to associate the beacon with a specific element.
triggerOnBundleBasketChangeBeacon(beaconUrl, element): sends onBundleBasketChange beacons for placement-level elements. This method should be called with the beacon URL when there is a change in the bundle basket within an ad placement. An optional element parameter can be used to associate the beacon with a specific element.

Product-level beacon handler

The ProductLevelBeaconHandler class provides various methods for handling product-level beacons. These beacons track user interactions with individual products (SKUs) within an ad unit.

triggerOnLoadBeacons(): sends onLoad beacons for elements with the data-criteo-product-onloadbeacon attribute. This method iterates over all elements with the specified attribute and sends a beacon for each element when the page loads.
attachOnViewBeacons(): attaches beacons to products with the data-criteo-product-onviewbeacon attribute. This method uses the IntersectionObserver API to monitor the visibility of ad placements and sends a beacon when an ad placement meets the viewability threshold according to IAB’s Viewable Impression Guidelines.
attachOnClickBeacons([jsEvent]): attaches onClick beacons to placements with the data-criteo-product-onclickbeacon attribute. If a JavaScript event is not provided, the click event will be used by default. The function will only attach to products loaded to the DOM with the specified attribute.
triggerOnBasketChangeBeacon(beaconUrl, element) Tracks when a user adds or removes an item from their shopping cart. An optional element parameter can be used to associate the beacon with a specific element.
triggerOnClickBeacon(beaconUrl, element) Tracks when a user clicks on a product within an ad unit. An optional element parameter can be used to associate the beacon with a specific element. You should use this method if you want to handle the click beaconing together with other routines.

​Introduction

​Quick Start

​Add Beacon Attributes to your HTML tags

​Page Intelligence placements

​Load BeaconSDK

​Implementation Examples

​Example 1: Basic integration

​Example 2: Dynamic content (lazy loading / SPA)

​Example 3: Placement-level Tracking

​Example 4: Video Placement

​Usage

​Dynamic Tracking

​Restricting Tracking to a Specific Container

​Tracking Organic Add-to-cart Events

​Setting the page-level context

​Required fields

​Recommended fields

​Optional fields

​Examples

​Tagging organic add-to-cart elements

​Required

​Optional

​Example

​What to verify

​Debugging

​Logging beacons

​Universal Beacons

​Viewability visualizer

​Getting BeaconSDK

​Stable version via <script> tag (Recommended)

​Version-specific endpoints

​Major version

​Minor version

​OneTag Bundle

​TypeScript NPM Package

​Installing and Self-hosting

​Installation

​Use the provided functions

​Placement-level beacon handler

​Product-level beacon handler

​What’s next

Introduction

Quick Start

Add Beacon Attributes to your HTML tags

Page Intelligence placements

Load BeaconSDK

Implementation Examples

Example 1: Basic integration

Example 2: Dynamic content (lazy loading / SPA)

Example 3: Placement-level Tracking

Example 4: Video Placement

Usage

Dynamic Tracking

Restricting Tracking to a Specific Container

Tracking Organic Add-to-cart Events

Setting the page-level context

Required fields

Recommended fields

Optional fields

Examples

Tagging organic add-to-cart elements

Required

Optional

Example

What to verify

Debugging

Logging beacons

Universal Beacons

Viewability visualizer

Getting BeaconSDK

Stable version via `<script>` tag (Recommended)

Version-specific endpoints

Major version

Minor version

OneTag Bundle

TypeScript NPM Package

Installing and Self-hosting

Installation

Use the provided functions

Placement-level beacon handler

Product-level beacon handler

What’s next