Skip to main content

​
Event Tracking

The Solute SDK provides comprehensive event tracking capabilities. Track custom events, page views, user identification, and more.

​
Track Custom Events

Track any custom event with properties: 
import { SoluteClient } from '@solute-ai/sdk';

const solute = new SoluteClient({
  apiKey: 'your_api_key',
  host: 'https://api.solute.dev',
});

// Track a simple event
solute.track('Button Clicked');

// Track an event with properties
solute.track('Button Clicked', {
  button_id: 'signup-cta',
  page: '/homepage',
  position: 'header',
  color: 'blue',
});

​
Identify Users

Identify users to associate events with specific users: 
// Identify a user with traits
solute.identify('user_123', {
  email: 'user@example.com',
  name: 'John Doe',
  plan: 'premium',
  created_at: '2025-01-01T00:00:00Z',
});

// Identify without traits (just set user ID)
solute.identify('user_123');
Call identify() as soon as you know the user’s ID. All subsequent events will be associated with this user.

​
Track Page Views

Track page views automatically or manually: 
// Automatic page view tracking (enabled by default)
// The SDK automatically tracks page views on route changes

// Manual page view tracking
solute.page('/pricing');

// Page view with properties
solute.page('/pricing', {
  category: 'Marketing',
  title: 'Pricing Page',
});

// Page view with name and category
solute.page('Pricing Page', {
  plan: 'premium',
}, 'Marketing');

​
Track Groups

Associate users with groups or organizations: 
// Associate user with a group
solute.group('company_123', {
  name: 'Acme Corp',
  plan: 'enterprise',
  employees: 50,
});

​
Alias User Identities

Merge anonymous and identified user identities: 
// When a user signs up, alias their anonymous ID with their user ID
solute.alias('user_123', 'anonymous_456');

​
Reset User

Reset the user identity (useful on logout): 
// Reset user and start a new session
solute.reset();

​
Flush Events

Force immediate sending of queued events: 
// Flush all queued events immediately
await solute.flush();
Events are automatically flushed based on your queue configuration. You typically don’t need to call flush() manually.

​
Event Properties

Event properties can include any JSON-serializable data: 
solute.track('Purchase Completed', {
  // Strings
  product_id: 'prod_123',
  currency: 'USD',
  
  // Numbers
  price: 99.99,
  quantity: 2,
  
  // Booleans
  is_premium: true,
  
  // Arrays
  tags: ['electronics', 'gadgets'],
  
  // Objects
  metadata: {
    source: 'web',
    campaign: 'summer-sale',
  },
  
  // Dates (will be serialized to ISO strings)
  purchased_at: new Date(),
});

​
Automatic Context

The SDK automatically enriches all events with context:
  • Page information: URL, path, referrer, title
  • User agent: Browser and device information
  • Screen: Screen dimensions and density
  • Locale: User’s locale and timezone
  • Session: Session ID
  • Library: SDK name and version

​
Next.js Integration

In Next.js, use hooks for event tracking: 
'use client';

import { useTrack, useIdentify } from '@solute-ai/sdk/nextjs';

export function SignupButton() {
  const track = useTrack();
  const identify = useIdentify();

  const handleSignup = async () => {
    // Identify user after signup
    identify('user_123', {
      email: 'user@example.com',
    });

    // Track signup event
    track('User Signed Up', {
      method: 'email',
      plan: 'free',
    });
  };

  return <button onClick={handleSignup}>Sign Up</button>;
}

​
Best Practices

Use clear, consistent event names like Button Clicked, Purchase Completed, or User Signed Up. Avoid generic names like click or action.
Add properties that help you understand the context of the event. Include IDs, categories, and any relevant metadata.
Call identify() as soon as you know the user’s ID to associate all events with the user.
Be mindful of privacy. Only track personally identifiable information (PII) if necessary and with user consent.

​
Next Steps

Feature Flags

Learn about feature flags and A/B testing

Next.js Integration

Deep dive into Next.js integration