User Management

The Seekora SDK provides user identification features for personalization and analytics tracking.

User Identifiers

The SDK manages three types of identifiers:

Identifier	Description	Persistence
userId	Authenticated user ID	Set manually on login
anonId	Anonymous user ID	localStorage (browser) / memory (Node.js)
sessionId	Session ID	sessionStorage (browser) / memory (Node.js)

Set User ID

Call setUserId when a user logs in:

// User logs in
client.setUserId('user-123');

// Subsequent searches and events will include this user ID
const results = await client.search('laptop');
await client.trackClick(itemId, 1, results.context);

Clear User ID

Call clearUserId when a user logs out:

// User logs out
client.clearUserId();

// SDK continues to use anonymous ID
const results = await client.search('laptop');

Get Identifiers

Retrieve the current identifiers:

const identifiers = client.getIdentifiers();

console.log('User ID:', identifiers.userId);      // 'user-123' or undefined
console.log('Anonymous ID:', identifiers.anonId); // Auto-generated UUID
console.log('Session ID:', identifiers.sessionId); // Auto-generated UUID

Initial Configuration

You can set identifiers when creating the client:

const client = new SeekoraClient({
  storeId: 'your-store-id',
  readSecret: 'your-read-secret',
  userId: 'user-123',        // Pre-authenticated user
  anonId: 'custom-anon-id',  // Custom anonymous ID
  sessionId: 'custom-session', // Custom session ID
});

User Flow Example

Here's a complete example of handling user authentication:

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

class SearchService {
  private client: SeekoraClient;

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

  // Call when user logs in
  onLogin(userId: string) {
    this.client.setUserId(userId);
    console.log('User ID set:', userId);
  }

  // Call when user logs out
  onLogout() {
    this.client.clearUserId();
    console.log('User ID cleared');
  }

  // Search with user context
  async search(query: string) {
    const results = await this.client.search(query);
    
    // Context includes userId if set
    console.log('Search context:', results.context);
    
    return results;
  }

  // Get current user state
  getUserState() {
    const ids = this.client.getIdentifiers();
    return {
      isAuthenticated: !!ids.userId,
      userId: ids.userId,
      anonId: ids.anonId,
      sessionId: ids.sessionId,
    };
  }
}

// Usage
const searchService = new SearchService();

// Anonymous user searches
await searchService.search('laptop');
// context.userId = undefined

// User logs in
searchService.onLogin('user-123');

// Authenticated user searches
await searchService.search('laptop');
// context.userId = 'user-123'

// User logs out
searchService.onLogout();

// Back to anonymous
await searchService.search('laptop');
// context.userId = undefined

React Integration

Example of integrating with React authentication:

import { createContext, useContext, useEffect, useState } from 'react';
import { SeekoraClient } from '@seekora-ai/search-sdk';

// Create context
const SeekoraContext = createContext<SeekoraClient | null>(null);

// Provider component
function SeekoraProvider({ children, user }) {
  const [client] = useState(() => new SeekoraClient({
    storeId: 'your-store-id',
    readSecret: 'your-read-secret',
  }));

  // Sync user ID with authentication state
  useEffect(() => {
    if (user?.id) {
      client.setUserId(user.id);
    } else {
      client.clearUserId();
    }
  }, [user?.id, client]);

  return (
    <SeekoraContext.Provider value={client}>
      {children}
    </SeekoraContext.Provider>
  );
}

// Hook to use client
function useSeekoraClient() {
  const client = useContext(SeekoraContext);
  if (!client) {
    throw new Error('useSeekoraClient must be used within SeekoraProvider');
  }
  return client;
}

// Usage in component
function SearchComponent() {
  const client = useSeekoraClient();
  const [results, setResults] = useState(null);

  const handleSearch = async (query: string) => {
    const searchResults = await client.search(query);
    setResults(searchResults);
  };

  return (
    // ... your search UI
  );
}

Anonymous ID Persistence

Browser

In browsers, the anonymous ID is stored in localStorage:

// Stored as
localStorage.getItem('seekora_anon_id');

// Session ID stored as
sessionStorage.getItem('seekora_session_id');

Node.js

In Node.js, identifiers are stored in memory and reset on restart. For persistence, provide your own IDs:

// Load from your persistence layer
const savedAnonId = await database.getAnonId();

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

Personalization

When user IDs are provided, the Seekora API can provide personalized results based on:

• Previous search history
• Click behavior
• Purchase history
• User preferences

// Personalized search for authenticated user
client.setUserId('user-123');

const results = await client.search('recommended products', {
  // Personalization is applied automatically
});

Privacy Considerations

• Anonymous ID: Generated using UUID v4, no personally identifiable information
• User ID: You control what ID is passed (e.g., internal user ID, not email)
• Session ID: Resets on browser close (sessionStorage)
• Data retention: Configure in your Seekora dashboard

To disable user tracking entirely:

const client = new SeekoraClient({
  storeId: 'your-store-id',
  readSecret: 'your-read-secret',
  anonId: 'anonymous',  // Use a constant instead of unique ID
  autoTrackSearch: false,
});

Next Steps

• TypeScript Types - Type definitions reference