Skip to main content

​
Event Tracking

Track custom events, page views, and user interactions with Signal JS.

​
Custom Events

​
Simple Event

signal.capture('button_clicked');

​
Event with Properties

signal.capture('purchase_completed', {
  amount: 99.99,
  currency: 'USD',
  productId: 'prod_123',
  quantity: 2,
});

​
Event with Timestamp

signal.capture('order_shipped', {
  orderId: 'order_456',
}, {
  timestamp: new Date('2024-01-15T10:00:00Z'),
});

​
Super Properties

Properties automatically included with every event:

​
Register Super Properties

// Register super properties
signal.register({
  appVersion: '2.1.0',
  environment: 'production',
  platform: 'web',
});

​
Register Once

// Register only if not already set
signal.registerOnce({
  firstVisitDate: new Date().toISOString(),
});

​
Remove Super Property

// Remove a super property
signal.unregister('environment');

​
Get All Super Properties

const props = signal.getSuperProperties();

​
Page Tracking

​
Automatic Page Views

Enable automatic page view tracking: 
const signal = createSignal({
  // ... other config
  capturePageview: true,  // Default: true
  capturePageleave: true,  // Default: true
});

​
Manual Page View

// Manual page view
signal.capturePageview({
  path: '/products/123',
  title: 'Product Details',
});

​
Track SPA Navigation

For single-page applications, track navigation manually: 
// Track SPA navigation
window.addEventListener('popstate', () => {
  signal.capturePageview();
});

// Or with your router
router.onRouteChange((route) => {
  signal.capturePageview({
    path: route.path,
    title: route.title,
  });
});

​
Recording Controls

Control when events are sent: 
// Start recording (called automatically on init)
await signal.start();

// Pause recording (events still tracked, replay paused)
signal.pauseRecording();

// Resume recording
signal.resumeRecording();

// Stop recording entirely
signal.stopRecording();

// Check recording state
signal.isRecording();  // true/false

// Get current session ID
signal.getSessionId();

// Get current window ID
signal.getWindowId();

// Force flush pending events
await signal.flush();

// Shutdown SDK gracefully
await signal.shutdown();

​
Example: Complete Event Tracking

import { createSignal } from '@signal-js/browser';

const signal = createSignal({
  apiKey: 'your-api-key',
  projectId: 'your-project-id',
  
  // Enable automatic page tracking
  capturePageview: true,
  capturePageleave: true,
});

await signal.start();

// Register super properties
signal.register({
  appVersion: '2.1.0',
  environment: 'production',
});

// Track custom events
function handleButtonClick(buttonId) {
  signal.capture('button_clicked', {
    buttonId,
    page: window.location.pathname,
  });
}

function handlePurchase(amount, productId) {
  signal.capture('purchase_completed', {
    amount,
    productId,
    currency: 'USD',
  });
}

// Track page views manually (for SPAs)
function trackPageView(path, title) {
  signal.capturePageview({
    path,
    title,
  });
}

​
Event Structure

All events follow this structure: 
interface SignalEvent {
  type: string;           // Event type
  name?: string;          // Event name
  timestamp: number;      // Unix timestamp (ms)
  sessionId: string;      // Session ID (UUIDv7)
  windowId: string;       // Window/tab ID (UUIDv7)
  distinctId?: string;    // User ID
  properties?: object;    // Event properties
  event?: object;         // Event-specific data (rrweb, network, etc.)
}

​
Event Types

TypeDescription
rrwebSession replay event (DOM mutations, interactions)
$pageviewPage view event
$pageleavePage leave event
$identifyUser identification
$groupidentifyGroup association
$performancePerformance metrics
consoleConsole log event
customCustom tracked event

​
Use Cases

  • Track user interactions - Button clicks, form submissions, etc.
  • Monitor conversions - Purchase events, sign-ups, etc.
  • Measure engagement - Page views, time on page, etc.
  • Debug issues - Track errors and user flows
  • Analytics - Understand user behavior and patterns

​
Best Practices

  1. Use descriptive event names - purchase_completed instead of event1
  2. Include relevant properties - Add context that helps with analysis
  3. Use super properties - Set common properties once, not per event
  4. Track key user actions - Focus on events that matter for your business
  5. Test your events - Verify events are being captured correctly