Skip to main content

Event Tracking

Track custom events, actions, and tags to enrich your session recordings with business context. Event tracking helps you understand what users are doing and correlate behavior with specific actions in your application.

Overview​

Recapt provides three types of events:

TypePurposeDeduplicationPropertiesTimestamped
TagLabel sessions (e.g., "premium_user", "trial")Yes (per session)NoNo
ActionTrack user actions (e.g., "checkout_started")No (can repeat)NoYes
CustomRich events with metadataNo (can repeat)YesYes

The Track API​

The track API provides a unified way to send all event types:

window.recapt('track', {
  event: 'event_name',      // Required: The event name
  type: 'custom',           // Optional: 'tag', 'action', or 'custom' (default)
  properties: { ... }       // Optional: Additional data (custom events only)
});

Sending Tags​

Tags are session-level labels that help you categorize and filter sessions. Each tag is deduplicated per session.

// Mark a session with a tag
window.recapt("track", { event: "premium_user", type: "tag" });
window.recapt("track", { event: "enterprise_plan", type: "tag" });
window.recapt("track", { event: "beta_tester", type: "tag" });

Use tags for:

  • User segments (premium, trial, enterprise)
  • Feature flags (beta_tester, early_access)
  • Session categories (support_ticket, demo_session)

Sending Actions​

Actions track discrete user behaviors. Unlike tags, actions can repeat within a session.

// Track user actions
window.recapt("track", { event: "checkout_started", type: "action" });
window.recapt("track", { event: "added_to_cart", type: "action" });
window.recapt("track", { event: "search_performed", type: "action" });

Use actions for:

  • Conversion funnel steps
  • Feature usage
  • User interactions

Sending Custom Events​

Custom events support properties, allowing you to attach metadata to events.

// Track a purchase with details
window.recapt("track", {
  event: "purchase_completed",
  properties: {
    amount: 99.99,
    currency: "USD",
    plan: "pro",
    annual: true,
  },
});

// Track a search with context
window.recapt("track", {
  event: "search",
  properties: {
    query: "pricing",
    results_count: 15,
    category: "docs",
  },
});

// Track an error with details
window.recapt("track", {
  event: "checkout_error",
  properties: {
    error_code: "CARD_DECLINED",
    step: "payment",
  },
});

Property value types:

  • string (max 500 characters)
  • number
  • boolean
  • null

Limits:

  • Event name: max 100 characters
  • Property key: max 50 characters
  • Max properties per event: 20

Real-World Examples​

E-commerce Funnel​

// Product viewed
window.recapt("track", {
  event: "product_viewed",
  properties: {
    product_id: "SKU-123",
    product_name: "Pro Plan",
    price: 29.99,
  },
});

// Added to cart
window.recapt("track", {
  event: "added_to_cart",
  type: "action",
});

// Checkout started
window.recapt("track", {
  event: "checkout_started",
  type: "action",
});

// Purchase completed
window.recapt("track", {
  event: "purchase_completed",
  properties: {
    order_id: "ORD-456",
    total: 29.99,
    currency: "USD",
  },
});

SaaS Onboarding​

// User signed up
window.recapt("track", { event: "signed_up", type: "action" });

// Tag the user's plan
window.recapt("track", { event: "trial_user", type: "tag" });

// Track onboarding steps
window.recapt("track", {
  event: "onboarding_step_completed",
  properties: {
    step: 1,
    step_name: "profile_setup",
    time_spent_seconds: 45,
  },
});

// Feature first used
window.recapt("track", {
  event: "feature_first_use",
  properties: {
    feature: "dashboard_export",
    source: "onboarding_tooltip",
  },
});

Error Tracking​

// Track form validation errors
window.recapt("track", {
  event: "form_validation_error",
  properties: {
    form: "signup",
    field: "email",
    error: "invalid_format",
  },
});

// Track API errors
window.recapt("track", {
  event: "api_error",
  properties: {
    endpoint: "/api/checkout",
    status: 500,
    error_code: "INTERNAL_ERROR",
  },
});

React / Next.js Integration​

Create a helper hook for type-safe event tracking:

// hooks/useRecaptTrack.ts
type TrackEventType = "tag" | "action" | "custom";

interface TrackEvent {
  event: string;
  type?: TrackEventType;
  properties?: Record<string, string | number | boolean | null>;
}

export function useRecaptTrack() {
  const track = (trackEvent: TrackEvent) => {
    if (typeof window !== "undefined" && window.recapt) {
      window.recapt("track", trackEvent);
    }
  };

  const tag = (name: string) => {
    track({ event: name, type: "tag" });
  };

  const action = (name: string) => {
    track({ event: name, type: "action" });
  };

  return { track, tag, action };
}

Usage in components:

function CheckoutButton({ product }) {
  const { track, action } = useRecaptTrack();

  const handleClick = () => {
    action("checkout_started");

    track({
      event: "checkout_initiated",
      properties: {
        product_id: product.id,
        price: product.price,
      },
    });

    // Continue with checkout...
  };

  return <button onClick={handleClick}>Checkout</button>;
}

Best Practices​

  1. Use consistent naming: Adopt a naming convention like noun_verb (e.g., checkout_started, form_submitted)

  2. Keep event names short: Event names are limited to 100 characters, but shorter is better for readability

  3. Don't over-track: Focus on meaningful events that help you understand user behavior

  4. Use tags for segments: Tags are great for categorizing sessions, not for tracking actions

  5. Include relevant context: Custom event properties should provide actionable context

  6. Avoid PII in properties: Don't include personally identifiable information in event properties

TypeScript Support​

For TypeScript projects, you can extend the Window interface:

declare global {
  interface Window {
    recapt: (
      action: "track" | "identify" | "start" | "stop" | "pause" | "resume",
      data?: any,
    ) => void;
  }
}

interface TrackEvent {
  event: string;
  type?: "tag" | "action" | "custom";
  properties?: Record<string, string | number | boolean | null>;
}

Next Steps​