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, browsing
- Product Recommendation : impressions, views, clicks
- 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
- Carousel of product recommendations
- 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.
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, landing page, brand pages with a product listing, etc.):
data-sf-component="product-list"
Search Result Pages
Main container of a search results page:
data-sf-component="product-search"
Product Recommendation
Main container of each product recommendation carousel (as you can have several carousel in the same page)
data-sf-component="product-recommendation"
You must also add the following attributes to each recommendation carousel container:
data-sf-recommendation-slot-id=xxx
data-sf-recommendation-config-id=yyy
The values of these attributes must correspond to the slotId and configId returned by Sensefuel API. They are used to identify which recommendation widget generated an impression, click, or conversion, enabling accurate analytics and performance reporting.
Product Tiles
Each product tile displayed within a product list, search results page, or recommendation carousel:
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"
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>