Complete documentation for all TraceLog client methods and configuration options.

Core Methods

TraceLog.init(config)

Initialize TraceLog with your configuration.

Parameters:

• config (AppConfig) - Configuration options

Returns: Promise

Example:

import { TraceLog } from '@tracelog/client';

await TraceLog.init({
  id: 'your-project-id'
});

Note: Always await initialization and ensure the DOM is fully loaded before calling TraceLog.init().

Full Configuration:

await TraceLog.init({
  id: 'your-project-id',
  sessionTimeout: 900000, // 15 minutes (default)
  globalMetadata: {
    version: '1.0.0',
    environment: 'production'
  },
  scrollContainerSelectors: ['.main-content'],
  sensitiveQueryParams: ['token', 'password'],
  allowHttp: false, // default: false
  integrations: {
    googleAnalytics: {
      measurementId: 'G-XXXXXXXXXX'
    }
  }
});

TraceLog.event(name, metadata?)

Send a custom event.

Parameters:

• name (string) - Event name
• metadata (Record<string, MetadataType>, optional) - Additional data

Examples:

// Simple event
TraceLog.event('user_signup');

// Event with data
TraceLog.event('product_purchase', {
  productId: 'prod-123',
  price: 29.99,
  currency: 'USD'
});

TraceLog.destroy()

Clean up TraceLog instance and remove all event listeners.

TraceLog.destroy();

Configuration Options (AppConfig)

Required

• id (string) - Your project ID from TraceLog dashboard

Optional

• sessionTimeout (number) - Session timeout in milliseconds (default: 900000 = 15 minutes, minimum: 30000 = 30 seconds, maximum: 86400000 = 24 hours)
• globalMetadata (object) - Data automatically added to every event
• scrollContainerSelectors (string | string[]) - Custom scroll containers to track
• sensitiveQueryParams (string[]) - Query parameters to remove from URLs
• allowHttp (boolean) - Allow HTTP requests (default: false, useful for development)
• integrations (object) - Third-party integrations

Automatic Events

TraceLog automatically tracks these events without any code:

• PAGE_VIEW - Page navigation and route changes
• CLICK - Button and link interactions
• SCROLL - Scroll depth tracking
• SESSION_START - When a new session begins
• SESSION_END - When a session ends

Metadata Types

Metadata values can be:

• string - Text values
• number - Numeric values
• boolean - True/false values
• string[] - Arrays of strings (max 10 items)

Limits

• Event names: 120 characters max
• Metadata: 8KB total size per event
• Keys: 10 keys max per event
• String arrays: 10 items max

Integrations

Google Analytics Integration

Connect TraceLog with Google Analytics 4 to send events to both platforms simultaneously.

integrations: {
  googleAnalytics: {
    measurementId: 'G-XXXXXXXXXX' // Your GA4 measurement ID
  }
}

Features:

• Automatically sends custom events to GA4
• Maintains consistent event naming between platforms
• No additional gtag configuration needed
• Works with existing GA4 setup

Example with GA4:

await TraceLog.init({
  id: 'your-project-id',
  integrations: {
    googleAnalytics: {
      measurementId: 'G-ABC123DEF4'
    }
  }
});

// This event will be sent to both TraceLog and GA4
TraceLog.event('purchase', {
  orderId: 'ORDER-123',
  total: 99.99
});

Error Handling

TraceLog handles errors gracefully:

• Network failures are retried automatically
• Invalid events are logged and skipped
• Initialization errors are logged to console
• App continues to work even if tracking fails

Examples

E-commerce Tracking

// Product view
TraceLog.event('product_view', {
  productId: 'SKU-123',
  category: 'electronics',
  price: 199.99
});

// Add to cart
TraceLog.event('add_to_cart', {
  productId: 'SKU-123',
  quantity: 1,
  cartTotal: 199.99
});

// Purchase
TraceLog.event('purchase', {
  orderId: 'ORDER-456',
  total: 199.99,
  items: ['SKU-123']
});

User Actions

// Form interactions
TraceLog.event('form_submit', {
  formType: 'contact',
  source: 'homepage'
});

// Feature usage
TraceLog.event('feature_used', {
  feature: 'search',
  query: 'analytics tools'
});

// User registration
TraceLog.event('user_signup', {
  method: 'email',
  source: 'landing_page'
});

Session Management

// Initialize when app starts
await TraceLog.init({
  id: 'your-project-id'
});

// Clean up when user logs out or app unmounts
TraceLog.destroy();