Event Tracking

FilterIQ tracks shopper interactions on your storefront using a client-side analytics library (analytics-client.js). This page covers the event model, the public tracking API, and how to integrate with your own analytics tools.

Architecture

Events flow through this pipeline:

Shopper interaction (click, search, filter)
    |
SmartSearchAnalytics client (analytics-client.js)
    |
Event queue (batched, 5-second interval)
    |
App Proxy (/apps/search-filter/api/analytics/event)
    |
Backend analytics service
    |
Analytics database

Events are batched and sent every 5 seconds to minimize network overhead. On page unload, remaining events are flushed via navigator.sendBeacon() for reliability.

Event Types

Session Events

Event	Trigger	Properties
`session_start`	First interaction in a new session	`is_new_visitor`, `device_type`

Search Events

Event	Trigger	Properties
`search_submit`	Shopper performs a search	`query`, `result_count`, `response_time_ms`
`search_click`	Shopper clicks a search result	`query`, `product_id`, `position`

Filter Events

Event	Trigger	Properties
`filter_select`	Shopper selects a filter option	`filter_key`, `filter_value`, `is_selected`, `collection_handle`
`filter_clear`	Shopper clears a filter	`filter_key`, `clear_type` (single or all)

Result Events

Event	Trigger	Properties
`results_viewed`	Search results page loads	`query`, `result_count`
`product_click`	Shopper clicks a product card	`product_id`, `position`, `source`

Conversion Events

Event	Trigger	Properties
`add_to_cart`	Shopper adds item from search results	`product_id`, `variant_id`, `source`
`purchase`	Order completed (via Shopify checkout)	`order_id`, `total`, `item_count`

Public JavaScript API

The analytics client exposes a global SmartSearchAnalytics class. You can access the active instance via window.SmartSearchAnalytics.

Methods

// Track a filter selection
window.SmartSearchAnalytics.trackFilterSelect(
  'color',     // filterName
  'Black',     // filterValue
  true         // isSelected
);

// Track a filter clear
window.SmartSearchAnalytics.trackFilterClear('color');  // single filter
window.SmartSearchAnalytics.trackFilterClear();          // clear all

// Track a search
window.SmartSearchAnalytics.trackSearchSubmit(
  'blue shoes',  // query
  42,            // resultsCount
  35             // responseTimeMs (optional)
);

// Track a product click
window.SmartSearchAnalytics.trackProductClick(
  'gid://shopify/Product/123',  // productId
  3,                              // position in results
  'search'                        // source: 'search' or 'filter'
);

Custom Event Tracking

You can also track custom events:

window.SmartSearchAnalytics._enqueue('custom_event', {
  action: 'compare_clicked',
  product_ids: ['123', '456'],
});

Custom DOM Events

The app dispatches custom DOM events that you can listen to for integration with third-party analytics:

// Fired when a search is performed
document.addEventListener('ssf:search', function(e) {
  console.log('Search query:', e.detail.query);
  console.log('Results:', e.detail.resultCount);
  // Send to Google Analytics, Segment, etc.
});

// Fired when a filter is selected
document.addEventListener('ssf:filter', function(e) {
  console.log('Filter:', e.detail.filterKey, e.detail.filterValue);
});

Session Management

Sessions are identified by a random UUID stored in sessionStorage
A new session starts when the shopper opens a new tab or their session storage is cleared
The session_start event fires once per session (tracked via sessionStorage.ssf_session_started)
New vs. returning visitor status is tracked via localStorage

Batch Configuration

Setting	Default	Description
Batch interval	5,000ms	How often queued events are sent
Max batch size	50 events	Maximum events per batch request
Beacon fallback	Enabled	Use `sendBeacon` on page unload

Privacy

No personally identifiable information (PII) is collected
Session IDs are random UUIDs with no connection to shopper identity
IP addresses are not stored by the analytics service
All data is scoped to shop_domain for tenant isolation
Analytics data is retained for 90 days (individual events) or indefinitely (aggregates)

Disabling Analytics

If you need to disable analytics tracking (e.g., for GDPR compliance with a cookie consent banner):

// Before the analytics client initializes
window.SSF_DISABLE_ANALYTICS = true;

Or conditionally based on cookie consent:

if (!userHasConsentedToAnalytics()) {
  window.SSF_DISABLE_ANALYTICS = true;
}