HomeGuidesChangelog
Log In
Guides

BeaconSDK

Suggest Edits

Introduction

The BeaconSDK library allows simplifying the Ad tracking implementation. It is designed to simplify the ad tracking implementation for developers.

When a retailer integrates with Criteo’s Retail Media ecosystem using the Direct Ad Server solution, the event-tracking logic needs to be implemented by the retailer’s own development team.

This task can be time-consuming, difficult to review, and generate non-standardized data. BeaconSDK solves that by providing industry-compliant viewability measurement, using the same viewability facilities from Criteo’s OneTag solutions.

On this page, we explain how to obtain it, and how to get started with BeaconSDK.

Overview

BeaconSDK supports all of Criteo’s standard and proprietary ad formats and provides both placement and product-level tracking.

Process overview integrating with the BeaconSDK

Process overview integrating with the BeaconSDK

📘

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

Getting BeaconSDK

We offer 2 options to get BeaconSDK:

  1. Typescript npm package: You can ask your Technical Account Manager (TAM) to provide the latest version of the npm package and use it directly in your project. See installation instructions below.
  2. OneTag bundle: If you leverage Criteo's OneTag to track events via our Marketing Solutions suite or for offsite campaigns, it can run the latest version of BeaconSDK for you. Please consult with your TAM to enable this solution.

Quick-start guide

The Criteo BeaconSDK allows developers to easily integrate and manage beacons for placement and product-level tracking in their applications. This guide will walk you through the installation and setup process, complete with a basic example to get you started.

Prerequisites

Make sure you have the following before you begin:

  • Node.js and npm installed on your machine.
  • Typescript installed as a npm package

Step 1: Prepare your project

Install TypeScript

First, ensure TypeScript is installed in your project. This SDK requires TypeScript for its type definitions.

npm install typescript

Install the Criteo BeaconSDK package

Use npm to install the SDK package:

npm install criteo-beacon-sdk-x.y.z.tgz

Set up the SDK directory

Copy the necessary SDK files to a directory within your project. This helps keep your project organized.

mkdir beacon-sdk
cp -r node_modules/@criteo/beacon-sdk/dist/mjs/* beacon-sdk

Step 2: Import and use the SDK

Import classes

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';

// 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();
/* [...]

Basic usage

In its most basic form, Beacon SDK will observe all HTML elements with attributes in the form of data-criteo-[beacon-level]-[beacon-type] and send the beacon on its corresponding event.

The value of each attribute should be the unique beacon URL provided by [Criteo’s Delivery API response].

Here is an example of the final HTML document for a sponsored product placement. Notice that Sponsored products don’t have an OnClickBeacon at the placement level (this type of beacon is present in Commerce Display formats only):

<div class="sponsored-product-placement"
     data-criteo-placement-onloadbeacon="//b.criteo.com/rm?rm_e=1234"
     data-criteo-placement-onviewbeacon="//b.criteo.com/rm?rm_e=5678"
     data-criteo-placement-onclickbeacon=""
>
  <div class="sponsored-product-tile"
       data-criteo-product-onloadbeacon="//b.criteo.com/rm?rm_e=abcd"
       data-criteo-product-onviewbeacon="//b.criteo.com/rm?rm_e=efgh"
       data-criteo-product-onclickbeacon="//b.criteo.com/rm?rm_e=ijkl"
  >
   <!--- Sponsored product card HTML elements here -->
  </div>
</div>

Three main types of beacons will be monitored:

  • OnLoadBeacon: triggered when the HTML element loads, regardless of whether the ad is in the user's viewport. It is triggered immediately when BeaconSDK detects the HTML element.
  • OnViewBeacon: triggered according to IAB’s Viewable Impression Guidelines
  • OnClickBeacon: triggered by default on the click event of its corresponding element.

Besides these three main types, BeaconSDK provides extra methods to handle other types of beacons and events. (See below).

Installation and importing

BeaconSDK is provided as a compressed TypeScript package. Once transpiled, the library is compliant with both CommonJS and ES6+.

  • Run npm install to ensure that TypeScript is installed.
  • Download the .tgz file criteo-beacon-sdk-x.y.z.tgz (where x.y.z is the SDK version) and then move the .tgz file into your project directory.
  • Install it by executing npm install criteo-beacon-sdk-x.y.z.tgz (ensure you replace x.y.z with the version string of your package)

After installing the BeaconSDK, you can import its functionalities directly into your project.

import PlacementtLevelBeaconHandler from '[PROJET_DIRECTORY]/FormatLevelBeaconHandler';  
import ProductLevelBeaconHandler from '[PROJET_DIRECTORY]/SkuLevelBeaconHandler';  
import ViewabilityVisualizer from '[PROJET_DIRECTORY]/debug/SkuViewabilityVisualizer';

Placement-level beacons

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 beacons

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.

Debug mode

The debug mode is a special mode to assist with troubleshooting and debugging. To enable it, simply enter the following command in the console of your browser's developer tools:

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

Once enabled, all beaconing events will be logged in the browser’s console.

Viewability visualizer

Once a product's view beacon is sent, the product viewability visualizer displays a checkmark on the product tile for 3 seconds and then restores the element to its original state and style.

This makes it easier for developers to visually check the corresponding view beacons that have just been sent.

To enable the viewability visualizer, import the visualizer and call the observe method. This only needs to be called once to apply to all pages.

import { ViewabilityVisualizer } from '@criteo/beacon-sdk';  
ViewabilityVisualizer.observe();

⚠️

Please use the viewability visualizer only in pre-production environments since, if deployed, end users will see the checkmark animation.

BeaconSDK in the integration timeline

With BeaconSDK integrated into your project, the ad rendering and beaconing phase should be considerably shortened.

Simple implementation example

Here's a basic example to illustrate how to use the SDK to handle different types of beacons.

This example listens for DOM events and triggers beacons based on user interactions.

It assumes that your backend system already requested the sponsored products from Criteo's delivery API and inserted the beacon URLs in the respective parameters by the rendering system.

BeaconSDK will call the URLs as the respective event happens.

📘

Read more about event types on the Beacon types page.

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Criteo BeaconSDK Example</title>
    <link href="style.css" rel="stylesheet" type="text/css">
    <script type="module" src="beacon-sdk-importer.js"></script>
</head>
<body>
    <div class="sponsored-product-placement"
         data-criteo-placement-onloadbeacon="//b.us5.uscriteo.com/rm?rm_e=1234"
         data-criteo-placement-onviewbeacon="//b.us5.uscriteo.com/rm?rm_e=5678"
         data-criteo-placement-onclickbeacon="">
      <div class="sponsored-product-tile"
           data-criteo-product-onloadbeacon="//b.us5.uscriteo.com/rm?rm_e=abcd"
           data-criteo-product-onviewbeacon="//b.us5.uscriteo.com/rm?rm_e=efgh"
           data-criteo-product-onclickbeacon="//b.us5.uscriteo.com/rm?rm_e=ijkl">
        <div class="add-to-wishlist" data-criteo-product-onwishlistbeacon="//b.us5.uscriteo.com/rm?rm_e=pqrs">
          <button>Add to Wishlist</button>  
        </div>
        <div>
          <span>This is a sponsored product</span>
        </div>
        <div class="add-to-cart" data-criteo-product-onbasketchangebeacon="//b.us5.uscriteo.com/rm?rm_e=lmno">
          <button>Add to Cart</button>  
        </div>
      </div>
    </div>
</body>
</html>

import PlacementLevelBeaconHandler from '/beacon-sdk/PlacementLevelBeaconHandler.js';
import ProductLevelBeaconHandler from '/beacon-sdk/ProductLevelBeaconHandler.js';

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

// Wait for the DOM to be fully loaded before attaching and triggering beacons
document.addEventListener('DOMContentLoaded', () => {
    // Attach and trigger beacons for placements
    PlacementLevelBeaconHandler.attachOnViewBeacons();
    PlacementLevelBeaconHandler.triggerOnLoadBeacons();

    // Attach and trigger beacons for products
    ProductLevelBeaconHandler.attachOnViewBeacons();
    ProductLevelBeaconHandler.triggerOnLoadBeacons();
    ProductLevelBeaconHandler.attachOnClickBeacons();

    // Set up event listeners for "Add to Wishlist" buttons
    const wishlistButtons = document.querySelectorAll('[data-criteo-product-onwishlistbeacon]');
    wishlistButtons.forEach(button => {
        button.addEventListener('click', (ev) => {
            ev.stopPropagation();
            ProductLevelBeaconHandler.triggerOnWishListBeacon(button.dataset.criteoProductOnwishlistbeacon);
        }, { once: true });
    });

    // Set up event listeners for "Add to Cart" buttons
    const addToCartButtons = document.querySelectorAll('[data-criteo-product-onbasketchangebeacon]');
    addToCartButtons.forEach(button => {
        button.addEventListener('click', (ev) => {
            ev.stopPropagation();
            ProductLevelBeaconHandler.triggerOnBasketChangeBeacon(button.dataset.criteoProductOnbasketchangebeacon);
        }, { once: true });
    });
});

Updated 3 months ago