Event Types

EventProperties

A flexible key-value map for custom event properties.

export interface EventProperties {
  [key: string]: string | number | boolean | null | undefined;
}

Properties

string | number | boolean | null | undefined

Dynamic properties that can be attached to any event. Keys are strings, and values can be strings, numbers, booleans, null, or undefined.

AnalyticsEvent

The core event structure used internally by the SDK.

export interface AnalyticsEvent {
  id: string;
  timestamp: number;
  type: "track" | "page" | "identify" | "alias" | "heatmap" | "session" | "error" | "subscription" | "payment";
  event?: string;
  properties?: EventProperties;
  userId?: string;
  anonymousId: string;
  sessionId: string;
  context: {
    page?: PageProperties;
    userAgent?: string;
    timezone?: string;
    locale?: string;
    screen?: {
      width: number;
      height: number;
    };
    library: {
      name: string;
      version: string;
    };
    performance?: PerformanceData;
    heatmap?: HeatmapData;
    session?: SessionData;
    error?: ErrorData;
  };
}

Properties

string

required

Unique identifier for this event.

number

required

Unix timestamp (in milliseconds) when the event occurred.

string

required

Type of event. Possible values: track, page, identify, alias, heatmap, session, error, subscription, payment.

string

Name of the event (e.g., “Button Clicked”, “Form Submitted”).

EventProperties

Custom properties associated with the event.

string

The identified user ID if available.

string

required

Anonymous identifier for the user, generated automatically if no userId is set.

string

required

Unique identifier for the current session.

object

required

Contextual information about the event:

page (PageProperties): Page-related information
userAgent (string): Browser user agent string
timezone (string): User’s timezone
locale (string): User’s locale
screen (object): Screen dimensions (width, height)
library (object): SDK information (name, version)
performance (PerformanceData): Performance metrics
heatmap (HeatmapData): Heatmap interaction data
session (SessionData): Session information
error (ErrorData): Error details

BackendEvent

Backend-compatible event structure for API submission.

export interface BackendEvent {
  event_id?: string;
  event_type: string;
  user_id?: string;
  session_id?: string;
  timestamp?: string;
  properties?: EventProperties;
  user_agent?: string;
  ip_address?: string;
}

Properties

string

Unique identifier for the event.

string

required

Type/name of the event being tracked.

string

The user’s ID if they are identified.

string

Current session identifier.

string

ISO 8601 formatted timestamp string.

EventProperties

Custom properties for the event.

string

Browser user agent string (auto-extracted by backend).

string

User’s IP address (auto-extracted by backend).

PageProperties

Properties specific to page view events.

export interface PageProperties {
  title?: string;
  url?: string;
  path?: string;
  referrer?: string;
  search?: string;
}

Properties

string

Page title from the document.

string

Full URL of the page.

string

URL path (without domain).

string

Referrer URL that led to this page.

string

Query string parameters.

UserProperties

Properties for identifying users.

export interface UserProperties {
  subscription?: SubscriptionProperties;
  [key: string]: string | number | boolean | null | undefined | SubscriptionProperties;
}

Properties

SubscriptionProperties

User’s subscription information.

Additional custom user properties.

PaymentEventProperties

Extended properties for payment-related events.

export interface PaymentEventProperties extends EventProperties {
  amount?: number;
  currency?: string;
  payment_status?: "succeeded" | "failed" | "pending" | "refunded";
  failure_reason?: string;
  invoice_id?: string;
  charge_id?: string;
}

Properties

number

Payment amount in cents.

string

Currency code (e.g., “usd”, “eur”).

string

Status of the payment. Possible values: succeeded, failed, pending, refunded.

string

Reason for payment failure, if applicable.

string

Associated invoice identifier.

string

Payment processor charge identifier.

ConversionEvent

Event data for A/B test conversions.

export interface ConversionEvent {
  experimentId: string;
  eventName: string;
  eventValue?: number;
  properties?: EventProperties;
}

Properties

string

required

ID of the experiment this conversion is associated with.

string

required

Name of the conversion event.

number

Numeric value associated with the conversion (e.g., revenue).

EventProperties

Additional properties for the conversion event.

Core API

Hooks

Components

Types

EventProperties

Properties

AnalyticsEvent

Properties

BackendEvent

Properties

PageProperties

Properties

UserProperties

Properties

PaymentEventProperties

Properties

ConversionEvent

Properties

​EventProperties

​Properties

​AnalyticsEvent

​Properties

​BackendEvent

​Properties

​PageProperties

​Properties

​UserProperties

​Properties

​PaymentEventProperties

​Properties

​ConversionEvent

​Properties

EventProperties

Properties

AnalyticsEvent

Properties

BackendEvent

Properties

PageProperties

Properties

UserProperties

Properties

PaymentEventProperties

Properties

ConversionEvent

Properties