Skip to main content

Analytics

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

Event Types​

EventDescriptionKey Data
searchUser performs a searchquery, results_count
clickUser clicks a search resultitem_id, position
viewUser views a productitem_id
conversionUser completes a purchaseitem_id, value, currency
impressionProduct is displayeditem_id, position, list_type
CustomAny custom eventcustom 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,
  });
});

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 custom event:

await client.trackCustom(
  eventName: string,
  payload?: Partial<DataTypesEventPayload>,
  context?: SearchContext
);

Example:

// Track add to cart
await client.trackCustom('add_to_cart', {
  metadata: {
    item_id: 'product-123',
    quantity: 2,
    cart_value: 199.98,
  },
}, results.context);

// Track wishlist add
await client.trackCustom('add_to_wishlist', {
  metadata: {
    item_id: 'product-456',
  },
}, results.context);

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)
  await client.trackCustom('add_to_cart', {
    metadata: {
      item_id: clickedResult.id,
      quantity: 1,
    },
  }, results.context);

  // 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​