Skip to main content

Custom Events

Track business-critical events beyond errors.

Page Views​

// Automatic (with current URL)
Syntropy.capturePageview();

// Custom URL
Syntropy.capturePageview('/checkout/success');

Custom Events​

Track any event important to your application:

// Simple event
Syntropy.captureEvent('button_clicked', {
  buttonId: 'signup',
  location: 'header',
});

// Business event
Syntropy.captureEvent('purchase_completed', {
  orderId: 'order-123',
  amount: 99.99,
  currency: 'USD',
  items: 3,
});

// Feature usage
Syntropy.captureEvent('feature_used', {
  feature: 'dark_mode',
  action: 'enabled',
});

Conversation Events​

Use conversation events for chat and assistant workflows:

Syntropy.captureConversation('conversation_started', {
  conversationId: 'conv_123',
  channel: 'web_chat',
});

Syntropy.captureConversation('message_sent', {
  conversationId: 'conv_123',
  role: 'user',
  length: 128,
});

Syntropy.captureConversation('message_received', {
  conversationId: 'conv_123',
  role: 'assistant',
  structured: true,
});

Event Structure​

Events have this structure:

{
  type: 'custom', // or 'conversation'
  name: 'purchase_completed',
  timestamp: '2024-01-15T10:00:00Z',
  payload: {
    orderId: 'order-123',
    amount: 99.99,
  },
}

Use Cases​

Feature Adoption​

Syntropy.captureEvent('feature_used', {
  feature: 'export_pdf',
  firstTime: !user.hasUsedExport,
});

Funnel Tracking​

// Step 1
Syntropy.captureEvent('funnel_step', {
  funnel: 'checkout',
  step: 'cart_viewed',
});

// Step 2
Syntropy.captureEvent('funnel_step', {
  funnel: 'checkout',
  step: 'shipping_entered',
});

// Step 3
Syntropy.captureEvent('funnel_step', {
  funnel: 'checkout',
  step: 'payment_completed',
});

Error Context​

Track events that might lead to errors:

// Before risky operation
Syntropy.captureEvent('api_call_started', {
  endpoint: '/api/process',
  payloadSize: data.length,
});

try {
  await processData(data);
  Syntropy.captureEvent('api_call_succeeded', {
    endpoint: '/api/process',
  });
} catch (error) {
  // Error captured with context from previous events
  Syntropy.captureError(error);
}

Best Practices​

Use Consistent Naming​

// Good - consistent snake_case
Syntropy.captureEvent('user_signed_up');
Syntropy.captureEvent('order_placed');
Syntropy.captureEvent('feature_enabled');

// Avoid mixing styles
Syntropy.captureEvent('UserSignedUp');    // PascalCase
Syntropy.captureEvent('order-placed');     // kebab-case

Include Relevant Context​

// Good - includes useful context
Syntropy.captureEvent('search_performed', {
  query: searchQuery,
  resultsCount: results.length,
  filters: activeFilters,
  responseTime: duration,
});

// Less useful - minimal context
Syntropy.captureEvent('search');

Don't Over-Track​

Focus on events that:

  • Indicate business value (conversions, engagement)
  • Help debug errors (actions before crashes)
  • Track feature adoption

Avoid tracking every click or minor interaction.