∧pex

Tracking Events

Track pageviews, clicks, purchases, and custom events with the Apex SDK. Events are batched in memory and sent to your Apex instance automatically.

track()

The primary method for recording events. Call it anywhere after init().

import { track } from "@apex-inc/sdk";

track("button_click", { buttonId: "cta-hero", label: "Get Started" });
ParameterTypeDescription
eventrequiredstringName of the event. Use snake_case by convention (e.g. page_view, form_submit).
propertiesRecord<string, unknown>Arbitrary key-value pairs attached to the event. Numbers, strings, and booleans are recommended.

Naming Conventions

Use descriptive snake_case names. Avoid generic names like click — include context so events are useful in reports. Good examples: page_view, signup_started, purchase_completed.

Examples

Pageviews

track("page_view", {
  path: window.location.pathname,
  title: document.title,
  referrer: document.referrer,
});

Purchases

track("purchase_completed", {
  orderId: "ord_8x92k",
  total: 149.99,
  currency: "USD",
  plan: "pro_annual",
});

trackForm()

A convenience method that tracks a form_submit event and calls identify() with the submitter's email in a single call.

import { trackForm } from "@apex-inc/sdk";

trackForm({
  email: "jane@acme.co",
  formId: "demo-request",
  action: "/thank-you",
  fields: { company: "Acme", role: "VP Marketing" },
});
ParameterTypeDescription
emailrequiredstringThe submitter's email address. Also used for identity stitching.
formIdstringAn identifier for the form (e.g. 'demo-request', 'newsletter').
actionstringThe form's action URL or destination page.
fieldsRecord<string, unknown>Additional form field values to include as event properties.

Tip

trackForm() is the fastest way to connect a form submission to a known user. It handles both the event and the identity call for you.

How Batching Works

Events are not sent individually. The SDK queues them in memory and flushes the batch to POST /api/events when any of these conditions are met:

  1. Timer — every flushInterval milliseconds (default: 5 seconds)
  2. Queue size — when the queue reaches flushAt events (default: 20)
  3. Page lifecycle — on beforeunload or visibilitychange (browser only)

You can also force an immediate flush:

import { flush } from "@apex-inc/sdk";

flush();

Warning

Calling track() before init() logs a warning and drops the event. Always initialize the SDK first.

Next Steps

PreviousInstallationNextIdentity