Browser SDK

Install the package and initialize it once in browser-only code.

$ pnpm add tracwell

import { createTracwell } from "tracwell";

const analytics = createTracwell({
  collectionMode: "private",
  projectKey: "tw_live_...",
});

The package is safe to import during server rendering. Call createTracwell() only after the document is available. See the framework guides for the correct mount point.

Add the script before the closing body tag or through your framework's script component.

<script
  defer
  src="https://collect.tracwell.app/script.js"
  data-project-key="tw_live_..."
  data-collection-mode="private"
></script>

The script exposes window.tracwell. Use it to track custom events after the script loads.

The standard snippet omits consent and Do Not Track attributes when they match the defaults. Add the supported attributes below when needed.

data-project-key

Required. Your website’s public project key; never use a server key.

data-collection-mode

"private" (default) or "product". Keep this explicit and match your website settings. Product mode persists identity in localStorage.

data-consent

"granted" (default), "required", or "denied". Use "required" to wait for your consent integration before collecting events.

data-respect-do-not-track

"true" (default) or "false". Omit it to respect the visitor’s Do Not Track setting.

<script
  defer
  src="https://collect.tracwell.app/script.js"
  data-project-key="tw_live_..."
  data-collection-mode="product"
  data-consent="required"
></script>

// Run after the SDK loads, when your consent integration confirms the choice.
window.tracwell?.setConsent("granted");

// When the visitor withdraws consent:
window.tracwell?.setConsent("denied");

Collection and identity creation wait until consent is granted. Read the visitor’s saved choice after the script loads and forward later changes from your consent integration.

The script reads these attributes when it loads; it does not fetch dashboard settings. If you change website settings, update the installed snippet to match. Other initialization options, such as batching, persistence overrides, or a custom collector URL, require the npm SDK.

Tracwell records the initial page automatically. It also observes pushState, replaceState, and browser back or forward navigation, covering normal path-based SPA routers.

Hash-only changes are ignored and URL fragments are excluded. Call analytics.page() only when your application changes the meaningful page without updating browser history.