RealanalyticsDocs
Documentation

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

Event schemas support scalar string, number, boolean, and string enum properties. Arrays, objects, dates, and null are not schema property types; flatten them into supported fields or serialize them deliberately to a string before tracking.

TypeExampleNotes
String"signup"Max 2000 characters
Number99.99Integers or floats
Booleantruetrue or false
String enum"pro"One of the values declared with p.enum()

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 })

Browser purchases are observations

A browser purchase_completed event is unverified. Use it for funnel instrumentation and debugging, not as authoritative revenue. Send trusted checkout, billing, renewal, and refund outcomes from your server through the Conversion API.

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,
  filter: '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