Analytics

The Seekora SDK provides comprehensive analytics tracking to help you understand user behavior and improve search performance.

Event Types

Event	Description	Key Data
search	User performs a search	query, results_count
click	User clicks a search result	item_id, position
view	User views a product	item_id
conversion	User completes a purchase	item_id, value, currency
impression	Product is displayed	item_id, position, list_type
Custom	Any custom event	custom payload

Search Context

Always use the SearchContext from search results to link events to searches:

const results = await client.search('laptop');

// Use results.context for all tracking calls
await client.trackClick(itemId, position, results.context);

SearchContext Structure

interface SearchContext {
  correlationId: string;  // Unique ID for this search journey
  searchId?: string;      // Search ID from backend
  userId?: string;        // User ID (if authenticated)
  anonId: string;         // Anonymous user ID
  sessionId: string;      // Session ID
}

Track Click

Track when a user clicks on a search result:

await client.trackClick(
  itemId: string,      // Product/item ID
  position: number,    // Position in results (1-indexed)
  context?: SearchContext
);

Example:

const results = await client.search('laptop');

// User clicks the first result
const clickedItem = results.results[0];
await client.trackClick(clickedItem.id, 1, results.context);

Track View

Track when a user views a product page:

await client.trackView(
  itemId: string,
  context?: SearchContext
);

Example:

// User navigates to product page
await client.trackView('product-123', results.context);

Track Conversion

Track when a user completes a purchase:

await client.trackConversion(
  itemId: string,
  value?: number,      // Order value
  currency?: string,   // Currency code (e.g., 'USD')
  context?: SearchContext
);

Example:

// User purchases a product
await client.trackConversion(
  'product-123',
  999.99,
  'USD',
  results.context
);

Track Impression

Track when products are displayed to the user:

await client.trackImpression({
  itemId: string,
  position: number,
  listType?: string,     // 'search_results', 'recommendations', etc.
  searchQuery?: string,
  context?: SearchContext,
  metadata?: Record<string, any>
});

Example:

// Track impressions for all visible results
results.results.forEach((result, index) => {
  client.trackImpression({
    itemId: result.id,
    position: index + 1,
    listType: 'search_results',
    searchQuery: 'laptop',
    context: results.context,
  });
});

Track Search

Manually track a search event (useful when autoTrackSearch is disabled):

await client.trackSearch({
  query: string,
  resultsCount: number,
  context?: SearchContext,
  analyticsTags?: string[],
  metadata?: Record<string, any>
});

Example:

await client.trackSearch({
  query: 'laptop',
  resultsCount: 150,
  context: results.context,
  analyticsTags: ['campaign:summer_sale'],
});

Track Custom Events

Track any domain-specific event that isn't covered by the built-in helpers. On the V4 analytics surface (Segment Spec) this is trackCustomEvent(ctx, eventName, properties). The ctx carries the Seekora analytics instance (window.SeekoraAnalytics, set up by Seekora's storefront snippet) plus your orgcode and xstoreid. See the Custom Events guide for the admin walkthrough and the Analytics Configuration guide for how to fetch your writeKey and the analytics ingest host.

import { trackCustomEvent } from '@seekora-ai/search-sdk';

// Seekora's storefront snippet exposes the analytics instance as
// window.SeekoraAnalytics. Build the tracking context once and reuse it.
const ctx = {
  analytics: window.SeekoraAnalytics,
  orgcode: 'YOUR_ORG_CODE',
  xstoreid: 'YOUR_STORE_ID',
};

trackCustomEvent(
  ctx,
  eventName: string,
  properties?: Record<string, any>
);

Example:

// Track add to cart
trackCustomEvent(ctx, 'add_to_cart', {
  item_id: 'product-123',
  quantity: 2,
  cart_value: 199.98,
});

// Track wishlist add
trackCustomEvent(ctx, 'add_to_wishlist', {
  item_id: 'product-456',
});

Track Generic Event

For maximum flexibility, use trackEvent:

await client.trackEvent(
  event: Partial<DataTypesEventPayload>,
  context?: SearchContext
);

Example:

await client.trackEvent({
  event_name: 'filter_applied',
  query: 'laptop',
  metadata: {
    filter_type: 'price',
    filter_value: '100-500',
  },
}, results.context);

Batch Events

Send multiple events in a single request (max 100 events):

await client.trackEvents(
  events: Array<Partial<DataTypesEventPayload>>,
  context?: SearchContext
);

Example:

const events = [
  { event_name: 'click', clicked_item_id: 'prod-1' },
  { event_name: 'click', clicked_item_id: 'prod-2' },
  { event_name: 'view', clicked_item_id: 'prod-3' },
];

await client.trackEvents(events, results.context);

Batch Limit

Maximum 100 events per batch. For larger batches, split into multiple calls.

Validate Events

Validate an event before sending:

const validation = await client.validateEvent({
  event_name: 'click',
  clicked_item_id: 'product-123',
});

if (!validation.valid) {
  console.error('Validation errors:', validation.errors);
}

Get Event Schema

Retrieve the event schema for reference:

const schema = await client.getEventSchema();
console.log(schema);

Complete Analytics Flow

Here's a complete example of tracking a user's search journey:

import { SeekoraClient } from '@seekora-ai/search-sdk';

const client = new SeekoraClient({
  storeId: 'your-store-id',
  readSecret: 'your-read-secret',
});

async function trackSearchJourney() {
  // 1. User searches
  const results = await client.search('laptop', {
    per_page: 20,
    analytics_tags: ['campaign:summer_sale'],
  });

  // 2. Track impressions for visible results
  results.results.slice(0, 10).forEach((result, index) => {
    client.trackImpression({
      itemId: result.id,
      position: index + 1,
      listType: 'search_results',
      searchQuery: 'laptop',
      context: results.context,
    });
  });

  // 3. User clicks on a result
  const clickedResult = results.results[2];
  await client.trackClick(clickedResult.id, 3, results.context);

  // 4. User views the product page
  await client.trackView(clickedResult.id, results.context);

  // 5. User adds to cart (custom event, V4 trackCustomEvent)
  trackCustomEvent(ctx, 'add_to_cart', {
    search_id: results.context.searchId,
    item_id: clickedResult.id,
    quantity: 1,
  });

  // 6. User completes purchase
  await client.trackConversion(
    clickedResult.id,
    clickedResult.price,
    'USD',
    results.context
  );
}

Analytics Tags

Use analytics tags to segment your data:

const results = await client.search('laptop', {
  analytics_tags: [
    'campaign:summer_sale',
    'source:homepage',
    'experiment:new_ranking',
  ],
});

Next Steps

• Configuration - Configure analytics behavior
• User Management - Track authenticated users