Custom events

Install and initialize Tracwell once in browser-only code. Add delivery callbacks while integrating so failures are visible instead of silent.

import { createTracwell } from "tracwell";

const analytics = createTracwell({
  collectionMode: "product",
  projectKey: "tw_live_...",
  onDelivery(report) {
    console.log("Tracwell delivery", report.status, report.eventIds);
  },
  onError(error) {
    console.error("Tracwell error", error.code, error.issues);
  },
});

Use private mode for privacy-preserving website analytics. Use product mode when you need persistent anonymous identity, sessions, or identify().

Name events after completed outcomes such as signup_completed, checkout_started, or report_exported. Keep the name stable and put changing values in properties.

For actions confirmed by your backend, follow the server events guide to record the result with the same visitor/session identity.

Call track() after the product action succeeds. A button click expresses intent; the confirmed result is the useful outcome.

async function handleSignup() {
  const account = await createAccount();

  analytics.track("signup_completed", {
    account_type: account.type,
    plan: account.plan,
  });
}

track() returns the event ID when the event enters the delivery queue. It returns undefined when collection is blocked or validation fails; onError provides the reason for validation failures.

const eventId = analytics.track("signup_completed", {
  plan: "starter",
  source: "pricing",
});

if (!eventId) {
  // Collection is blocked or the event did not pass validation.
}

Properties become filters and breakdowns in reports. Send dimensions you expect to compare later, using JSON-compatible strings, finite numbers, booleans, null, arrays, and nested objects.

analytics.track("report_exported", {
  format: "csv",
  filters: {
    country: "IN",
    range: "last_30_days",
  },
  included_sections: ["overview", "acquisition"],
  row_count: 1842,
});

A delivery status of accepted means the collector returned a matching acceptance receipt. handed_off means the browser handed the batch to sendBeacon while the page was leaving; it is not a server acceptance confirmation.

If you installed the CDN script instead of the npm package, call the same API through window.tracwell.

window.tracwell?.track("signup_completed", {
  plan: "starter",
  source: "pricing",
});