Articles in this section

See more

Sensefuel Behavioural Tracking with JavaScript tag

  • Updated

1. Overview

Sensefuel relies on a functional JavaScript tag combined with a DOM-based tracking approach to capture user interactions across your entire website.

The tag:

  • Enables Sensefuel features (search and recommendations)
  • Collects behavioral data
  • Powers analytics and AI learning

It is GDPR-compliant (strictly necessary) and does not require user consent.

For full details on deployment and configuration, please refer to the dedicated implementation documentation.

2. How Tracking Works

Once deployed and configuration set up by Sensefuel, the JavaScript tag continuously tracks user behavior directly from the front-end (DOM):

  • Listens to user interactions (clicks, navigation, actions)
  • Identifies elements using selectors (class, ID, attributes, URLs)
  • Sends structured events to Sensefuel systems

No backend integration is required.

3. Scope of Tracking

Tracking covers the entire user journey, including:

  • Navigation and browsing
  • Search usage
  • Product listings and product clicks
  • Product page views
  • Add to cart actions
  • Cart interactions
  • Checkout initiation

This enables a complete view of user behavior across the funnel

4. DOM-Based Tracking Principles

Tracking relies on detecting key elements such as:

  • Search inputs (search box, magnifying glass icon, or any element that needs to trigger the display of Sensefuel search Layer)
  • Product listings and product tiles
  • Action buttons (e.g. add to cart) in Product Detail Pages / Product Listing Pages
  • Cart validation and checkout elements such as the total amount

These elements are identified through front-end selectors

5. Key Constraint: Front-End Dependency

⚠️ Tracking depends entirely on your website’s DOM.

Any change to:

  • HTML structure
  • CSS classes or IDs
  • URL patterns

…can impact or break tracking. 

Any tracking disruption can lead to incomplete, inconsistent, or missing data in performance dashboards, while also degrading Sensefuel’s learning capabilities—ultimately impacting the ranking relevance of the search results, product recommendations, PLP ranking/browsing and conversational experience. To know more about Sensefuel Ranking Principles click here.

6. Client Responsibilities

6.1 Anticipate Front-End Changes

Please inform Sensefuel teams before:

  • Website redesign / replatforming
  • UI or component updates
  • Framework migration

6.2 Ensure Reliable Tracking - Recommendations

✅ Preferred

  • Dedicated data-sf-* attributes
  • Stable IDs when available
  • Explicit and uniquely identifiable elements

⚠️ Acceptable

  • CSS classes, provided they are stable, unique, and not reused for unrelated elements

❌ Avoid

  • Auto-generated framework classes
  • Dynamic selectors that change between deployments
  • Styling-only classes with no functional meaning
  • DOM structures that frequently change without notice

Following these recommendations helps ensure uninterrupted tracking, accurate analytics, and optimal performance of Sensefuel's search, recommendation, ranking, and AI learning systems.

6.3 Tracking Best Practices

To ensure reliable, maintainable, and future-proof tracking, Sensefuel can recommend to implement dedicated data-sf-* attributes on key website elements when the current elements of your website are not respecting the recommendations listed above.

These attributes should be:

  • Stable over time
  • Independent from CSS classes or the front-end framework
  • Preserved during design updates or website redesigns

Using dedicated tracking attributes significantly reduces the risk of tracking disruptions caused by UI changes and facilitates long-term maintenance.

HTML Attributes

Search

Search input, search trigger, or search icon responsible for opening the search experience:

data-sf-action="open-search"

Product Listing Pages

Main container of a product listing page (category, collection, merchandising page, etc.):

data-sf-component="product-list"

Main container of a search results page:

data-sf-component="product-search"

Product Tiles

Each product tile displayed within a product list or search results page:

data-sf-element="product-tile"

Add-to-cart button displayed within a product tile:

data-sf-action="add-to-cart"

Product Detail Pages

Main container of a product detail page:

data-sf-component="product-page"

Add-to-cart button displayed on the product detail page:

data-sf-action="add-to-cart"

Breadcrumb Navigation

Main breadcrumb container:

data-sf-component="breadcrumbs"

Cart Page

Main cart page container:

data-sf-component="cart-page"

Cart subtotal value (excluding shipping fees):

data-sf-element="cart-subtotal"

Checkout or order validation button:

data-sf-action="checkout"

Hierarchy Requirements

Child elements must always be contained within their corresponding parent component. This structure allows Sensefuel to correctly associate user interactions with the appropriate context.

Example:

<div data-sf-component="product-list"> 
  <article data-sf-element="product-tile"> 
    <button data-sf-action="add-to-cart"> 
      Ajouter au panier 
    </button> 
  </article> 
</div>