Analytics Overview

The toolkit/analytics module provides a standardized, type-safe, and asynchronous way to track events and manage user/session context across the application.

Key Concepts

1. AnalyticsTracker

The entry point for all analytics operations. It abstracts the complexity of data collection, property management, and dispatching.

  • Track Events: Record discrete actions like button clicks or page views.
  • Track Context: Update persistent properties like "User ID" or "App Version" that should be attached to future events.
  • Clear Context: Remove stale properties (e.g., on logout).

2. Events & Properties

We distinguish between "what happened" (Events) and "context of occurrence" (Context Properties).

AnalyticsEvent

Ephemeral data describing a specific action.

  • Name: Unique string identifier (e.g., login_clicked).
  • Event Properties: Key-value pairs specific to that single occurrence (e.g., button_color: blue).

ContextAnalyticsProperty

Persistent state answering "Who/Where/State".

  • Scope: Determines the lifecycle of the property.
    • SESSION: Persists until the app session ends.
    • USER: Persists until explicitly cleared or user logs out.
  • Automatic Enrichment: When an event is tracked, the tracker automatically merges relevant context properties from the global store into the event payload.

3. AnalyticsPipeline

The engine under the hood. It processes all analytics commands (track, clear) asynchronously on a background thread. This ensures that heavy analytics logic never blocks the main UI thread.

4. AnalyticsSink

Pluggable destinations for analytics data. You can have multiple sinks active simultaneously (e.g., Firebase, backend API, console logger).

Good to Know

  • Asynchronous: All track and clear calls are non-blocking. They return immediately, and the work is queued in the AnalyticsPipeline.
  • Thread Safety: The pipeline manages concurrency, so you can safely call track from any thread.
  • Precedence: If an event defines a property key that conflicts with a context property, the **event property wins **. This allows for specific overrides.