Skip to Content
DocumentationWeb SDKEvent Tracking

Event Tracking

Track custom events, page views, revenue, and user identification.

Custom Events

import { track } from '@attributehq/web-sdk'
 
// Simple event
track('signup_completed')
 
// Event with properties
track('product_viewed', {
  product_id: 'sku_123',
  category: 'electronics',
  price: 15000,
})
 
// Funnel event
track('checkout_step', {
  step: 2,
  step_name: 'payment_method',
})

Properties can be any JSON-serializable object. They’re stored as-is and available in analytics and webhook payloads.

Page Views

Page views are tracked automatically when autoTrackPageViews: true (the default). The SDK detects:

  • Initial page load
  • history.pushState() calls (React Router, Next.js, etc.)
  • history.replaceState() calls
  • Browser back/forward (popstate event)

Each page view automatically includes: url, path, title, and referrer.

To manually track a page view:

import { trackPageView } from '@attributehq/web-sdk'
 
trackPageView({ section: 'pricing' })

If your framework uses a custom routing mechanism that doesn’t call history.pushState, page views won’t auto-track. Use trackPageView() manually in your router’s navigation callback.

Revenue Events

import { trackRevenue } from '@attributehq/web-sdk'
 
// Basic revenue (defaults to NGN currency)
trackRevenue(5000)
 
// With currency
trackRevenue(25.99, 'USD')
 
// With additional properties
trackRevenue(5000, 'NGN', {
  product_id: 'plan_premium',
  payment_method: 'card',
  is_first_purchase: true,
})

Revenue events are flagged with revenue_amount and revenue_currency for LTV and ROAS calculations in the analytics dashboard.

User Identification

Associate events with a known user after login:

import { identify } from '@attributehq/web-sdk'
 
identify('user_12345', {
  email: 'user@example.com',
  plan: 'premium',
  signup_date: '2025-01-15',
})

The user ID is persisted in localStorage and included in subsequent events.

Event Batching

Events are not sent immediately. They’re queued in localStorage and flushed when:

  1. The queue reaches batchSize (default: 10 events)
  2. The flushInterval timer fires (default: every 5 seconds)
  3. You call flush() manually
  4. The page is being closed/hidden (via beacon)

Offline Support

If a flush fails (e.g., no network), events are put back in the queue and retried on the next flush cycle. The queue persists in localStorage across page loads.

If the queue exceeds maxQueueSize (default: 100), the oldest events are dropped.

Manual Flush

import { flush } from '@attributehq/web-sdk'
 
// Force send all queued events
flush()

Page Unload

On visibilitychange (hidden) and beforeunload, remaining events are sent via:

  1. fetch with keepalive: true — preferred, supports custom headers
  2. navigator.sendBeacon — fallback, API key embedded in request body

This ensures events are delivered even when the user closes the tab.

Session Management

Sessions group events that belong to the same user visit.

  • A new session is created on first init or when the previous session has been inactive for 30 minutes
  • Session IDs are UUIDs stored in localStorage
  • Each event includes the current session_id
  • Page view count is tracked per session

Sessions are purely client-side — no server round-trip required.

InstallationAttribution