Event Data

The EventData interface represents a fully enriched analytics event. It is produced by the Litetics and passed to your persist callback.

Type Definition

Every field in the enriched event is represented in the interface:

interface EventData {
  // Identity
  bid: string;
  receivedAt: Date;

  // Page
  host: string;
  path: string;
  queryString: string | null;
  hash: string | null;

  // Uniqueness
  isUniqueUser: boolean;
  isUniquePage: boolean;

  // Event
  type: 'pageview' | (string & { _?: never });
  durationMs: number | null;

  // Location
  timeZone: string | null;
  country: string | null;

  // User-Agent
  userAgent: string | null;
  browserName: string | null;
  browserVersion: string | null;
  browserEngineName: string | null;
  browserEngineVersion: string | null;
  deviceType: string | null;
  deviceVendor: string | null;
  deviceModel: string | null;
  cpuArchitecture: string | null;
  osName: string | null;
  osVersion: string | null;

  // Referrer
  referrer: string | null;
  referrerHost: string | null;
  referrerPath: string | null;
  referrerQueryString: string | null;
  referrerKnown: boolean | null;
  referrerMedium: string | null;
  referrerName: string | null;
  referrerSearchParameter: string | null;
  referrerSearchTerm: string | null;

  // Language
  acceptLanguage: string | null;
  languageCode: string | null;
  languageScript: string | null;
  languageRegion: string | null;
  secondaryLanguageCode: string | null;
  secondaryLanguageScript: string | null;
  secondaryLanguageRegion: string | null;

  // UTM
  utmCampaign: string | null;
  utmMedium: string | null;
  utmSource: string | null;
  utmTerm: string | null;
  utmContent: string | null;
  utmId: string | null;
  utmSourcePlatform: string | null;

  // Custom
  properties: Record<string, Primitive> | null;
}

Field Details

Each category of fields and their sources are described below.

Identity

Fields that identify the event and its origin:

Field	Source	Description
bid	Body b	Beacon ID generated by the tracker
receivedAt	Server	Timestamp when the event was processed

Page

Fields extracted from the page URL in the request body:

Field	Source	Description
host	Body u	Hostname of the page
path	Body u	Path with trailing slashes stripped. Root is /
queryString	Body u	Full query string or null
hash	Body u	Fragment including #, or null

Uniqueness

Fields indicating whether this visitor and page are new:

Field	Source	Description
isUniqueUser	Body p	New unique visitor today
isUniquePage	Body q	First visit to this specific page
durationMs	Body m	Set by unload beacon. null for active pageviews and one-time events

Location

Fields related to the user's geographic location:

Field	Source	Description
timeZone	Body t	IANA time zone from Intl.DateTimeFormat
country	Derived from t	ISO 3166-1 alpha-2 mapped via time zones DB

Referrer Mediums

Possible values for referrerMedium:

Value	Description
"search"	Search engine (Google, Bing, Yandex, etc.)
"social"	Social network (Twitter, Facebook, LinkedIn, etc.)
"email"	Email provider (Gmail, Yahoo, Outlook, etc.)
"internal"	Same hostname as the current page
"unknown"	Known domain but unknown category
null	Not in the referrer database

Event Types

The type field accepts 'pageview' for automatic page load tracking and any arbitrary string for custom events. The type union (string & { _?: never }) allows autocomplete for 'pageview' while permitting any string value.

Properties

The properties field carries the custom data from tracker.track():

await tracker.track('signup', {
  type: 'engagement', // → EventData.type
  plan: 'premium', // → EventData.properties.plan
  source: 'hero-cta', // → EventData.properties.source
});