Skip to main content

​
EventProperties

A flexible key-value map for custom event properties. 
export interface EventProperties {
  [key: string]: string | number | boolean | null | undefined;
}

​
Properties

​
[key: string]
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

​
id
string
required
Unique identifier for this event.
​
timestamp
number
required
Unix timestamp (in milliseconds) when the event occurred.
​
type
string
required
Type of event. Possible values: track, page, identify, alias, heatmap, session, error, subscription, payment.
​
event
string
Name of the event (e.g., “Button Clicked”, “Form Submitted”).
​
properties
EventProperties
Custom properties associated with the event.
​
userId
string
The identified user ID if available.
​
anonymousId
string
required
Anonymous identifier for the user, generated automatically if no userId is set.
​
sessionId
string
required
Unique identifier for the current session.
​
context
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

​
event_id
string
Unique identifier for the event.
​
event_type
string
required
Type/name of the event being tracked.
​
user_id
string
The user’s ID if they are identified.
​
session_id
string
Current session identifier.
​
timestamp
string
ISO 8601 formatted timestamp string.
​
properties
EventProperties
Custom properties for the event.
​
user_agent
string
Browser user agent string (auto-extracted by backend).
​
ip_address
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

​
title
string
Page title from the document.
​
url
string
Full URL of the page.
​
path
string
URL path (without domain).
​
referrer
string
Referrer URL that led to this page.
​
search
string
Query string parameters.

​
UserProperties

Properties for identifying users. 
export interface UserProperties {
  subscription?: SubscriptionProperties;
  [key: string]: string | number | boolean | null | undefined | SubscriptionProperties;
}

​
Properties

​
subscription
SubscriptionProperties
User’s subscription information.
​
[key: string]
string | number | boolean | null | undefined | SubscriptionProperties
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

​
amount
number
Payment amount in cents.
​
currency
string
Currency code (e.g., “usd”, “eur”).
​
payment_status
string
Status of the payment. Possible values: succeeded, failed, pending, refunded.
​
failure_reason
string
Reason for payment failure, if applicable.
​
invoice_id
string
Associated invoice identifier.
​
charge_id
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

​
experimentId
string
required
ID of the experiment this conversion is associated with.
​
eventName
string
required
Name of the conversion event.
​
eventValue
number
Numeric value associated with the conversion (e.g., revenue).
​
properties
EventProperties
Additional properties for the conversion event.

Build docs developers (and LLMs) love

Get started for freeTalk to us