SDK reference

Last updated Nov 9, 2026

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. Calls made before the first one are held, up to 100, and made once it runs.

Parameter	Type	Notes
`key`	`string`	The project's browser key: `tl_pk_` followed by 26 lowercase base32 characters. Public by design, bound to your site's addresses.
`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; the PrestaShop module and a page opened from the check derive it on their 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 check 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. A grant is not remembered: call it on every page load while the visitor's consent stands, so consent that expires or is withdrawn in your banner ends in TraceLog too.

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 check 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, options?: {
  items?: {
    id: string;
    name: string;
    category?: string;
    quantity: number;
    price?: number;
  }[];
}): void;

Records one declared step of the conversion path.

Parameter	Type	Notes
`name`	`string`	Must match the conversion path 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.
`options.items`	`array`	Optional, on a conversion or a step: up to 100, each an id, a name, an optional category, a quantity from 1 and an optional unit price.

JavaScript

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

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

conversion

TypeScript

conversion(name: string, options: {
  identifier: string;
  value?: number;
  currency?: string;
  context?: object;
  items?: {
    id: string;
    name: string;
    category?: string;
    quantity: number;
    price?: number;
  }[];
  scheduledFor?: string;
  recurring?: boolean;
  first?: boolean;
}): void;

Records the declared conversion.

Parameter	Type	Notes
`name`	`string`	The conversion's name in the conversion path, 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 — below 1 in 100 of a day's identifiers, a second value only warns.
`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.
`options.items`	`array`	Optional, on a conversion or a step: up to 100, each an id, a name, an optional category, a quantity from 1 and an optional unit price.
`options.scheduledFor`	`string`	Optional, on a conversion: the day it is for, YYYY-MM-DD.
`options.recurring`	`boolean`	Optional, on a conversion: whether it recurs.
`options.first`	`boolean`	Optional, on a conversion: `true` when your records hold no earlier conversion of this kind by the same person, `false` when they do; omit it when you do not know.

JavaScript

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

An item whose id is (other) is counted under Other, with the items past each day's 500.

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: the first page of a visit where the visitor has consented opens the session, and no page after it is recorded.