Reference

Browser API

@parlox/browser: init and its options, track, consent and sessionId, and the tag's attributes.

@parlox/browser 1.0.3. Every function is safe to call during server-side rendering, and none of them throws.

TypeScript
import { init, track, consent, sessionId } from "@parlox/browser";
import { ParloxAnalytics } from "@parlox/browser/react";

Both entries ship ES modules and CommonJS, with type declarations for each.

init

TypeScript
function init(options: InitOptions): ParloxApi | null;

Starts Parlox on this page. Call it once, as early as possible, in the browser. It returns the running instance, or null during server rendering or when the options are invalid (with a console.warn). A second call returns the instance already running.

OptionTypeDefault
publicKeystringrequiredThe site's public key, pk_…. Safe in the browser
consent"granted" or "required""granted""required": nothing is stored or sent until consent(true) (Consent)
recordAgentsbooleantrueRecord visits by automated browsers as a masked replay. false never loads the recorder (Agent recordings)
endpointstring"https://gateway.parlox.io"For testing against another deployment only. Must be https (http only for localhost and 127.0.0.1)

track

TypeScript
function track(name: string, props?: CommerceProps): void;

interface CommerceProps {
  value?: number;            // major units: 49.90
  currency?: string;         // ISO 4217: "USD"
  items?: number;            // a count
  order_id?: string | number;
  item_id?: string | number;
  step?: string;
}

Records a commerce event under a GA4 ecommerce name: view_item, add_to_cart, remove_from_cart, view_cart, begin_checkout, checkout_step, add_shipping_info, add_payment_info, purchase, search. Any other name is ignored, and so is any property not listed. Calls made before init are queued, at most 100, and sent in order once it runs. The events and when to send them: Cart and checkout events.

TypeScript
function consent(granted: boolean): void;

consent(true) starts Parlox if it was waiting for consent. consent(false) stops it at once, a running recording included, forgets the tab's visit id and its outbox, and sends nothing buffered.

sessionId

TypeScript
function sessionId(): string | null;

The visit's id: 24 lowercase hexadecimal characters, or null before init has run. Send it with your checkout so your server can post the confirmed order.

ParloxAnalytics

TSX
<ParloxAnalytics publicKey="pk_…" consent="required" recordAgents={false} />

For React and Next.js. It takes the same options as init, as props, renders nothing, and calls init once after hydration. The built file carries "use client". @parlox/browser/react also re-exports init, track, consent and sessionId.

window.parlox

Once init has run, or the tag has loaded, the same three functions are on window.parlox:

TypeScript
window.parlox.track("add_to_cart", { item_id: "sku-123", value: 49.9, currency: "USD", items: 1 });
window.parlox.consent(true);
window.parlox.sessionId();

With the tag, this stub before it queues track and consent calls made before it loads:

HTML
<script>window.parlox=window.parlox||{q:[],track:function(){window.parlox.q.push(['track'].concat([].slice.call(arguments)))},consent:function(g){window.parlox.q.push(['consent',g])}};</script>

The tag's settings

AttributeIn the script URL
data-key?key=pk_…The site's public key. Required
data-consent="required"consent=requiredWait for parlox.consent(true)

The tag reads nothing else. It sends to the origin it was loaded from, and loads its recorder from the same release, pinned by a hash.

Attributes in your markup

AttributeEffect on recordings
data-plx-unmaskText inside is recorded as it is
data-plx-maskEverything inside is masked, control labels included
data-plx-blockLeft out of the recording entirely