SDK reference

The entire public API of the TraceLog browser runtime — init, consent, step and conversion — with every parameter, its type, and an example.

These methods let you initialise TraceLog, manage consent, and send steps and conversions. The script tag exposes them on the global TraceLog; the npm package exports the same object as its default export.

init

TypeScript

init(options: {
  key: string;
  endpoint?: string;
  mode?: "verification";
}): void;

Starts the runtime. Safe to call more than once — the first call creates the engine and later ones re-apply the configuration.

Parameter	Type	Notes
`key`	`string`	The project's browser key: `tl_pk_` followed by 26 lowercase base32 characters. Public by design, bound to an origin allowlist.
`endpoint`	`string`	Where batches are posted. Defaults to `/v1/events`, relative to your own origin. Must be `http` or `https`.
`mode`	`"verification"`	Declares the session as verification traffic. The Shopify app and the WooCommerce plugin set it from the store's test-order signal; a page opened from a verification session derives it on its own.

JavaScript

TraceLog.init({ key: "tl_pk_xxxxxxxxxxxxxxxxxxxxxxxxxx" });

An invalid key or endpoint does not throw and does not capture: the runtime reports config_invalid to the verification session instead of failing your page.

TypeScript

consent.grant(): void;

Grants consent and starts capture. Before this call the runtime creates no identifier, writes no storage entry, and sends no request; a denial is remembered in one key and nothing else, so a visitor who refused is not asked again by the runtime.

JavaScript

TraceLog.consent.grant();

TypeScript

consent.deny(): void;

Denies consent. Capture stops and anything queued is discarded.

JavaScript

TraceLog.consent.deny();

TypeScript

consent.state(): "unknown" | "granted" | "denied";

Reads the current state. unknown means neither call has been made yet — it is not a synonym for denied, and the verification session uses the difference to tell "no runtime on the page" apart from "a consent banner is blocking us".

JavaScript

if (TraceLog.consent.state() === "unknown") showConsentBanner();

step

TypeScript

step(name: string, context?: object): void;

Records one declared step of the conversion path.

Parameter	Type	Notes
`name`	`string`	Must match the tracking plan and the event-name form: lowercase, starting with a letter, then letters, digits or underscores, up to 64 characters.
`context`	`object`	Optional. Any JSON-serialisable object, up to 8 KB serialised. Keys beginning with `__tl.` are TraceLog's and are removed.

JavaScript

TraceLog.step("begin_checkout", { cartSize: 3 });

A step whose name is not in the plan is still received; it simply is not part of what the plan is verified against.

conversion

TypeScript

conversion(name: string, options: {
  identifier: string;
  value?: number;
  currency?: string;
  context?: object;
}): void;

Records the declared conversion.

Parameter	Type	Notes
`name`	`string`	The conversion's name in the plan, in the same event-name form as a step.
`options.identifier`	`string`	Required, 1 to 256 characters. Your own stable identifier — an order number, lead id, booking reference. A conversion without it blocks verification, and so does one identifier arriving with conflicting data.
`options.value`	`number`	Optional, zero or greater.
`options.currency`	`string`	Optional, ISO 4217 as three uppercase letters, e.g. `EUR`.
`options.context`	`object`	Optional. Any JSON-serialisable object, up to 8 KB serialised. Keys beginning with `__tl.` are TraceLog's and are removed.

JavaScript

TraceLog.conversion("purchase", {
  identifier: "1042",
  value: 89.9,
  currency: "EUR",
});

What is not here

There is no method to read a metric, force a flush, set a user identity, or capture a page view. Batches are sent on their own schedule and when the page is hidden. TraceLog keeps no identity across sites, and does not capture page views, clicks or scroll.