JavaScript API

The tag exposes a single global, window.periscale, with the methods below. Use it when you need to track an event that doesn't have a natural DOM target.

track(event, properties?)

Fire a custom event with arbitrary properties.

window.periscale.track("video_played", {
  video_id: "promo-2026",
  duration_seconds: 60,
});

identify(distinctId, properties?)

Associate the current visitor with a known identity. All subsequent events use this distinctId.

window.periscale.identify("user-123", {
  email: "user@example.com",
  plan: "pro",
  first_name: "Ada",
});

The chat widget reads from the same identity store — once you call identify(), the visitor's chat session shows their email and name.

alias(newId, oldId?)

Merge two identities. Use this if a visitor signs up after starting as an anonymous user — alias() ties the new user id to the anonymous distinct id so historical events stay attributed.

window.periscale.alias("user-123");

group(groupType, groupKey, properties?)

Tag the visitor as belonging to a group (most often a "company" or "team") for cohort analysis.

window.periscale.group("company", "acme-inc", {
  plan: "enterprise",
  seats: 50,
});

reset()

Clear all identity and start a fresh anonymous session — call on logout.

window.periscale.reset();

optOut() / optIn() / hasOptedOut()

Honor a visitor's choice to disable tracking. After optOut(), all track() calls are silently dropped until optIn() is called.

window.periscale.optOut();          // user clicked "do not track"
window.periscale.optIn();           // user changed their mind
window.periscale.hasOptedOut();     // boolean

setSuperProperties(props)

Properties added here are attached to every event from now on. Use sparingly.

window.periscale.setSuperProperties({
  app_version: "2.4.1",
  experiment_variant: "B",
});

flush()

Force-send any queued events immediately. The tag normally batches every 10 seconds or 20 events.

window.periscale.flush();

getDistinctId()

Returns the current visitor id (anonymous or identified). Useful for client-side debugging or for correlating with your own logs.

console.log(window.periscale.getDistinctId());

init(options)

Call this only when you load the tag with data-no-init="true" (e.g. waiting for cookie consent before booting):

window.periscale.init({ apiKey: "sb_live_xxx" });

Option	Default	Description
apiKey	required	Your sb_live_* key.
autocapture	true	Set to false to disable DOM auto-capture.
capturePageview	true	Set to false to skip the initial $pageview.
engagement	true	Set to false to disable scroll-depth and time-on-page.
webVitals	true	Set to false to disable LCP/INP/CLS reporting.
errors	true	Set to false to disable JS exception capture.