Getting Started

Core Concepts

Understanding how Advaita models events, users, and sessions will help you instrument your product correctly from day one.

Events

An event is the fundamental unit of data in Advaita. Every event has three required fields and an optional properties object:

Field	Type	Description
`event`	`string`	The name of the action, e.g. `button_clicked` or `page_view`.
`user_id`	`string`	The authenticated user's ID. Optional if the user is anonymous.
`anonymous_id`	`string`	A device-level ID generated by the SDK for anonymous users.
`timestamp`	`ISO 8601`	When the event occurred. Defaults to server receipt time if omitted.
`properties`	`object`	Any JSON key-value pairs describing the event.

Event types

Advaita recognises three built-in event types that receive special treatment in the pipeline:

track()

Track

A user action. Name it with a verb + noun in snake_case: button_clicked, checkout_completed, feature_used.

page()

Page

A page or screen view. Automatically captures URL, referrer, and title in web SDKs.

identify()

Identify

Links an anonymous_id to a known user_id and attaches persistent user traits.

Properties

Properties are free-form key-value pairs attached to any event. Advaita auto-collects a set of context properties and merges them with your custom ones:

{
  // Your custom properties
  "plan": "pro",
  "button_id": "upgrade_cta",

  // Auto-collected context
  "$os": "macOS",
  "$browser": "Chrome 124",
  "$referrer": "https://google.com",
  "$session_id": "sess_a8f2k1",
  "$lib": "advaita-js-sdk@1.4.2"
}

Identity & users

Advaita uses a two-stage identity model:

Anonymous ID — Generated by the SDK on first load and persisted in local storage. Every event carries this ID so pre-login sessions are fully captured.
User ID — Your application's user identifier. Set this by calling identify() on login. Advaita merges the anonymous session history into the identified profile.

Always call identify() after a successful login, not before. The SDK will alias the anonymous session to the user ID automatically.

Sessions

A session begins when a user first loads your app and ends after 30 minutes of inactivity (configurable). Sessions are tracked automatically — you don't need to call any session methods.

Each session carries a unique $session_id so you can reconstruct the full user journey, measure session depth, and analyse drop-off by session number.

Schema & validation

Advaita has an optional schema registry. You can define expected properties and their types for any event name. When a captured event violates the schema, it is flagged in the Data Interface → Schema Health view but is still stored — nothing is dropped.

Schema enforcement modes:

Observe (default) — Capture everything, flag violations as warnings.
Warn — Store the event, alert the team, and surface in the dashboard.
Strict — Reject events that violate required fields. Not recommended for production without testing.

Ingest pipeline

Every event passes through the following stages before it is available for analysis:

Receipt — The ingest API acknowledges the event and assigns a server timestamp if none is provided.
Enrichment — IP geolocation, device parsing, and session stitching are applied.
Schema validation — The event is checked against your schema registry. Violations are flagged.
Storage — The event is written to your project's clickstream store, typically within 200ms of receipt.
Indexing — Event properties are indexed for fast funnel and cohort queries.