Tracking Events

Track custom events with the Realanalytics SDK

Basic Tracking

Use track() to record custom events:

analytics.track('button_clicked', {
  buttonId: 'signup-cta',
  buttonText: 'Start Free Trial',
  page: '/pricing',
})

Event Names

Event names should be:

  • Snake case: purchase_completed, not purchaseCompleted
  • Past tense: form_submitted, not form_submit
  • Descriptive: checkout_started, not click

Reserved prefix: $

Events starting with $ are reserved for autocaptured events like $pageview and $click.

Properties

Properties provide context about events:

// E-commerce example
analytics.track('purchase_completed', {
  orderId: 'order_123',
  total: 99.99,
  currency: 'USD',
  items: 3,
  couponUsed: true,
})

// Feature usage example
analytics.track('feature_used', {
  feature: 'export',
  format: 'csv',
  rowCount: 1500,
})

// Content engagement example
analytics.track('article_read', {
  articleId: 'abc123',
  title: 'Getting Started Guide',
  readTime: 240,
  scrolledToEnd: true,
})

Property Types

TypeExampleNotes
String"signup"Max 2000 characters
Number99.99Integers or floats
Booleantruetrue or false
Array["a", "b"]Converted to JSON string

Common Event Patterns

Conversions

// Sign up funnel
analytics.track('signup_started')
analytics.track('signup_completed', { plan: 'pro' })

// Checkout funnel
analytics.track('cart_viewed')
analytics.track('checkout_started')
analytics.track('payment_submitted')
analytics.track('purchase_completed', { total: 149.99 })

Feature Adoption

// Track feature discovery
analytics.track('feature_discovered', {
  feature: 'dark_mode',
  source: 'settings_page',
})

// Track feature usage
analytics.track('feature_used', {
  feature: 'dark_mode',
  enabled: true,
})

Search and Navigation

// Search
analytics.track('search_performed', {
  query: 'pricing',
  resultsCount: 12,
  filters: ['category:docs'],
})

// Navigation
analytics.track('navigation_clicked', {
  from: '/dashboard',
  to: '/settings',
  via: 'sidebar',
})

Tracking in React Components

import { analytics } from '@/lib/analytics'

function PricingCard({ plan }) {
  const handleSelect = () => {
    analytics.track('plan_selected', {
      plan: plan.name,
      price: plan.price,
      billingCycle: plan.cycle,
    })

    // Continue with selection logic...
  }

  return (
    <button onClick={handleSelect}>
      Select {plan.name}
    </button>
  )
}

Tracking on Page Load

// Track when component mounts
useEffect(() => {
  analytics.track('dashboard_viewed', {
    projectCount: projects.length,
    hasNotifications: notifications.length > 0,
  })
}, [])

Conditional Tracking

// Only track significant events
if (items.length > 0) {
  analytics.track('cart_updated', {
    itemCount: items.length,
    total: calculateTotal(items),
  })
}

// Track errors conditionally
if (error.severity === 'high') {
  analytics.track('critical_error', {
    code: error.code,
    message: error.message,
  })
}

Manual Flush

Events are batched and sent automatically. To force immediate sending:

// Track and immediately flush (useful before navigation)
analytics.track('checkout_completed', { orderId: '123' })
analytics.flush()

Next Steps