Configuration

The tag boots itself on load. Pass options only when you need to disable a feature, override an endpoint, or wait for consent before starting.

Two ways to configure: the <script> tag (most common) or window.periscale.init().

Script-tag attributes

<script
  src="https://cdn.periscale.app/analytics.min.js"
  data-api-key="sb_live_your_api_key_here"
  data-tenant="heronstore"
  data-autocapture="true"
  data-pageview="true"
  defer
></script>

See Tag attributes for the full attribute list.

init(options) — full reference

Call init() yourself when you load the tag with data-no-init="true" — for example, to wait for a cookie-consent banner before capturing anything:

<script src="https://cdn.periscale.app/analytics.min.js" data-no-init="true"></script>
<script>
  // later, after the visitor consents:
  window.periscale.init({ apiKey: "sb_live_xxx" });
</script>

Core

Option	Default	Description
apiKey	required	Your sb_live_* business key. Read from data-api-key if omitted.
tenant	resolved	Tenant/subdomain. Auto-resolved from the hostname; override with data-tenant or this option.

Feature toggles

Every subsystem is on by default. Set any to false to disable it.

Option	Default	Disables…
capturePageview	true	the initial $pageview event
autocapture	true	DOM data-p-* auto-capture (see Auto-capture)
engagement	true	scroll depth, time-on-page, rage & dead clicks
webVitals	true	LCP / INP / CLS / FCP / TTFB reporting
errors	true	JS exceptions and API error/slow-response capture
featureFlags	true	feature-flag & experiment evaluation
replay	true	session replay (see Session replay)
surveys	true	on-page surveys (see Surveys)
vendorTags	true	Microsoft Clarity + Facebook Pixel dedup (see below)

TIP

The quick-reference table on the JavaScript API page covers the four most common toggles. This page is the complete list.

Replay sampling

replay accepts either a boolean or an object:

window.periscale.init({
  apiKey: "sb_live_xxx",
  replay: { sampleRate: 0.1 }, // record ~10% of visitors
});

Option	Default	Description
sampleRate	0.25	Fraction of visitors (0–1) to record. Sticky per visitor.
rrwebUrl	(internal)	Override the recording-engine script URL.

Recording also requires the business to have PostHog configured — see Session replay.

Endpoint overrides

All analytics traffic flows through one base, which resolves automatically:

• Localhost → http://localhost:8787/analytics (the local worker)
• Everywhere else → https://secure.periscale.ai/analytics

You normally never touch these. They exist for self-hosting or proxying through your own domain:

Option	Default	Purpose
collectorUrl	…/ingest	Event ingestion endpoint (also settable via data-collector).
decideUrl	…/decide	Feature-flag evaluation.
configUrl	…/config	Per-business config (gates replay, vendor tags).
replayUrl	…/replay	Replay ingestion.
surveysActiveUrl	…/surveys/active	Active-survey listing.
surveysRespondUrl	…/surveys/respond	Survey response submission.

Disable everything, then opt in selectively

For the strictest consent posture, load with data-no-init="true" and enable only what the visitor approved:

window.periscale.init({
  apiKey: "sb_live_xxx",
  engagement: false,
  webVitals: false,
  errors: false,
  replay: false,
  surveys: false,
  vendorTags: false,
});

See Privacy & consent for opt-out cookies and Do Not Track.