Skip to main content
The Tracker module provides methods to send behavioral events to Constructor.io’s API. These events are crucial for understanding user behavior, improving search relevance, and personalizing product recommendations.

​
What is Behavioral Tracking?

Behavioral tracking captures user interactions with your site, such as:
  • Search queries and result interactions
  • Product browsing and clicks
  • Add-to-cart and purchase events
  • Recommendation views and clicks
  • Quiz interactions
Constructor.io uses this data to continuously improve search relevance, personalize results, and optimize your site’s performance.

​
Accessing the Tracker

The tracker is available as a property on the main Constructor.io client instance: 
import ConstructorIOClient from '@constructor-io/constructorio-client-javascript';

const constructorio = new ConstructorIOClient({
  apiKey: 'YOUR_API_KEY',
});

// Access tracker methods
constructorio.tracker.trackSessionStart();

​
Event Categories

The tracker supports several categories of events:

​
Session Events

  • Session Start: Track when a user session begins
  • Input Focus: Track when a user focuses on a search input

​
Search Events

  • Autosuggest Select: Track selections from autocomplete results
  • Search Submit: Track search query submissions
  • Search Results Loaded: Track when search results are displayed
  • Search Result Click: Track clicks on search results

​
Browse Events

  • Browse Results Loaded: Track when browse/category pages load
  • Browse Result Click: Track clicks on browse results

​
Recommendation Events

  • Recommendation Results Loaded: Track when recommendation pods are displayed
  • Recommendation Result Click: Track clicks on recommended items

​
Quiz Events

  • Quiz Result Click: Track clicks on quiz results
  • Quiz Conversion: Track conversions from quiz results

​
Conversion Events

  • Conversion: Track add-to-cart and other conversion events
  • Purchase: Track completed purchases

​
Common Parameters

Many tracking methods accept common parameters:

​
Network Parameters

All tracking methods accept an optional networkParameters object: 
constructorio.tracker.trackSessionStart({
  timeout: 5000, // Request timeout in milliseconds
});

​
Analytics Tags

Many methods support analyticsTags for passing custom analytics data: 
constructorio.tracker.trackSearchSubmit(
  'running shoes',
  {
    originalQuery: 'shoes',
    analyticsTags: {
      campaign: 'summer-sale',
      source: 'email',
    },
  }
);

​
Section Parameter

The section parameter specifies the index section (defaults to “Products”): 
constructorio.tracker.trackConversion(null, {
  itemId: '123',
  section: 'Products',
});

​
Automatic Session Management

The SDK automatically manages session IDs and client IDs. These are included with all tracking events to associate actions with specific users and sessions.

​
Return Values

All tracking methods return either true on success or an Error object if validation fails. The actual HTTP requests are queued and sent asynchronously. 
const result = constructorio.tracker.trackSessionStart();
if (result instanceof Error) {
  console.error('Tracking failed:', result.message);
}

​
Best Practices

  1. Track Session Start: Call trackSessionStart() when a user first arrives on your site
  2. Include Result IDs: Always pass resultId from Constructor.io responses to click events
  3. Track All Interactions: Track both views and clicks for complete behavior data
  4. Use Item IDs Consistently: Ensure item IDs match those in your product catalog
  5. Track Conversions: Link conversions back to the search terms that led to them
  6. Track Purchases: Always track completed purchases with order details

Build docs developers (and LLMs) love

Get started for freeTalk to us