Fullstory Analytics Events API

Implementation Files: This document covers core concepts. For code examples, see:

• SKILL-WEB.md — JavaScript/TypeScript (Browser)
• SKILL-MOBILE.md — iOS, Android, Flutter, React Native

Overview

Fullstory's Analytics Events API allows developers to send custom event data that captures meaningful user actions and business moments. Unlike automatic capture which records all interactions, trackEvent lets you define semantically meaningful events with rich context that can be used for:

• Funnel Analysis: Track conversion steps and drop-off points
• Feature Adoption: Measure feature usage and engagement
• Business Metrics: Capture revenue, conversions, and KPIs
• User Journeys: Define key moments in user workflows
• Segmentation: Create user segments based on behaviors

Beyond the DOM

Analytics events are especially valuable for capturing data that isn't visible in the DOM or native view hierarchy:

• Network/API Data: AJAX response errors, correlation IDs, request header values, API latency
• Framework Internals: React component render times, Angular state errors, Vue lifecycle issues
• Performance Metrics: Time-to-interactive, lazy load completion, bundle load times
• Background Processes: WebSocket events, service worker activity, push notification delivery
• Error Context: Stack traces, error codes, failed validation details

This makes trackEvent the bridge between your application's internal state and Fullstory's observability.

Core Concepts

Events vs Properties vs Elements

When to Use Events

Key principle: Events capture moments in time. Page properties capture state that persists across interactions.

✅ Use trackEvent for:

• Discrete actions that happen at a specific point in time
• Business-critical moments (purchases, signups, conversions)
• Feature usage tracking
• Funnel step completion
• Data not in the DOM (API responses, framework errors, performance metrics)
• Background process completions (data sync, file upload finished)

❌ Don't use trackEvent for:

• Clicks (Fullstory captures automatically)
• Page views (use page properties instead)
• User attributes (use user properties instead)
• High-frequency interactions (scroll, mouse move)
• Stateful context that applies to multiple interactions (use page properties)

Events vs Page Properties: Point-in-Time vs State

Rule of thumb: If the data remains true while the user interacts with the page, it's a page property. If it's something that happened, it's an event.

Event Naming Conventions

Fullstory recommends semantic event naming following industry standards:

[Object] [Action]

Examples:
- "Product Added"
- "Order Completed"
- "Feature Enabled"
- "Search Performed"
- "Video Played"
- "Subscription Started"
- "Trial Converted"

Naming Rules

Standard Event Names by Category

E-commerce:

• Product Viewed, Product Added, Product Removed
• Cart Viewed, Checkout Started, Order Completed
• Coupon Applied, Payment Failed

SaaS:

• Feature Used, Feature Enabled, Feature Disabled
• Trial Started, Trial Converted, Trial Expired
• Subscription Started, Plan Changed, Subscription Cancelled

Engagement:

• Search Performed, Search Result Clicked
• Content Viewed, Video Played, Video Completed
• Form Started, Form Completed, Form Abandoned

Technical/System (non-DOM data):

• API Error Occurred, API Call Completed
• Component Render Slow, Hydration Failed
• State Error Detected, Framework Exception
• WebSocket Disconnected, Sync Completed
• Performance Threshold Exceeded, Bundle Loaded

Event Properties

Every event can include rich contextual properties that enable deep analysis.

Property Naming

Supported Property Types

Type Inference

Fullstory auto-infers types, but explicit schemas ensure accuracy:

Limits and Constraints

Size Limits

Rate Limits

Array Handling

Best Practices

1. Event Design Checklist

Before implementing an event, answer:

• What question does this answer? (e.g., "How many users complete checkout?")
• What properties enable analysis? (e.g., order_id, revenue, item_count)
• How often will it fire? (Watch rate limits)
• Is it redundant? (Don't duplicate auto-captured data)

2. Property Design Principles

• Include identifiers: order_id, product_id, feature_name
• Include context: source, entry_point, page_name
• Include metrics: revenue, quantity, duration_ms
• Include state: is_first_order, is_trial, status

3. Deduplication

For events that might fire multiple times (form submissions, button clicks):

Strategy: Track a unique key (e.g., order_id) and skip if seen recently

4. Timing Events

For events with duration (video watched, form completed):

Strategy: Track start time, calculate duration on completion
Include: duration_ms, completed (bool), cancel_reason (if abandoned)

Troubleshooting

Events Not Appearing

Properties Not Indexed

Common Type Mistakes

Fullstory Search Examples

Find Events by Name

Event where name = "Order Completed"

Filter by Property

Event where name = "Order Completed" and revenue > 100

Find Events with Specific Value

Event where name = "Feature Used" and feature_name = "advanced_export"

Combine with User Properties

Event where name = "Order Completed" and user.plan = "enterprise"

Find Abandoned Funnels

Event where name = "Checkout Abandoned" and abandoned_at_step = 2

Key Takeaways for Agent

When helping developers implement Analytics Events:

1. Always emphasize:

   • Use semantic event names (Object + Action)
   • Include meaningful properties
   • Use schema for non-string types
   • Don't track what Fullstory captures automatically
   • Events = moments in time; Page properties = persistent state
   • Events are ideal for non-DOM point-in-time data (API errors, performance failure events, framework internals)

2. Common mistakes to watch for:

   • Generic event names ("click", "action")
   • Missing critical properties (order_id, revenue)
   • Type format mismatches
   • Over-tracking micro-interactions
   • Using events for stateful data describing a page or user (should be page or user properties)
   • Using page properties for point-in-time occurrences (should be events)

3. Questions to ask developers:

   • What business questions will this event answer?
   • What properties are needed for segmentation?
   • How often will this event fire?
   • Is this redundant with auto-captured data?
   • Is this a moment in time, or state that persists?
   • Is this data visible in the DOM, or only in code?

4. Platform routing:

   • Web (JavaScript/TypeScript) → See SKILL-WEB.md
   • iOS (Swift/SwiftUI) → See SKILL-MOBILE.md § iOS
   • Android (Kotlin) → See SKILL-MOBILE.md § Android
   • Flutter (Dart) → See SKILL-MOBILE.md § Flutter
   • React Native → See SKILL-MOBILE.md § React Native

Reference Links

• Analytics Events (Web): https://developer.fullstory.com/browser/capture-events/analytics-events/
• Analytics Events (iOS): https://developer.fullstory.com/mobile/ios/capture-events/analytics-events/
• Analytics Events (Android): https://developer.fullstory.com/mobile/android/capture-events/analytics-events/
• Analytics Events (Flutter): https://developer.fullstory.com/mobile/flutter/capture-events/analytics-events/
• Analytics Events (React Native): https://developer.fullstory.com/mobile/react-native/capture-events/analytics-events/
• Custom Properties: https://developer.fullstory.com/browser/custom-properties/
• Help Center - Custom Events: https://help.fullstory.com/hc/en-us/articles/360020623274