JavaScript SDK — OpenAnalyticsAPI Docs

Installation

Add this single tag to the <head> of your site. It loads asynchronously and does not block rendering.

HTML

<script async defer
  src="https://www.openanalyticsapi.com/sdk/oa.js"
  data-site="YOUR_SITE_ID"></script>

data-site is your public site_id — safe to expose in HTML. It is not an API token.

What gets tracked automatically

Pageviews on initial load and on SPA navigation (pushState / popstate)
Session start / end / bounce with 30-minute inactivity timeout
Anonymous user ID stored in localStorage; session ID stored in sessionStorage
Browser, OS, device type, screen and viewport size
Country, region, city, timezone — derived server-side from the anonymized IP
Referrer and UTM parameters (utm_source, utm_medium, utm_campaign, utm_term, utm_content)
Language preference from navigator.language

No cookies are set on the visitor's device in default mode. The snippet automatically respects the browser's Do Not Track signal when data-respect-dnt="true" is set on the script tag, and never sends events for headless browsers / known crawlers.

Manual API

Once the snippet has loaded, window.oa(...) is available. Calls made before load are queued and replayed after init, so it's safe to invoke oa() from inline scripts that may run earlier.

Custom event

window.oa('event', 'signup', { plan: 'pro', source: 'pricing_page' });

Identify call

Associate the current anonymous user with a stable identifier. Hash or pseudonymize before sending — do not pass raw emails.

window.oa('identify', 'user_123', { plan: 'pro' });

Conversion

window.oa('conversion', 'purchase', {
  revenue:  49.99,
  currency: 'USD',
  plan:     'pro'
});

Manual pageview

Useful for SPAs that don't use the History API, or when you want to record a virtual pageview after a state change.

window.oa('pageview', { url: '/virtual/checkout-step-2' });

Opt-out / opt-in

window.oa('optOut') immediately halts tracking on this browser. The tracker stops sending events, clears the locally-stored anonymous ID and session ID, and notifies the replay/heatmap addons to drop their buffers. The opt-out is persisted in localStorage and survives reloads.

window.oa('optIn') removes the opt-out flag. A page reload is recommended so the tracker can fully re-initialize for the current page view:

window.oa('optOut');

// Later, after the user re-consents:
window.oa('optIn');
window.location.reload();

A fresh anonymous ID is generated on the next page load — pre-opt-out and post-opt-in activity are not linked. See GDPR & privacy for the consent-banner pattern.

Configuration attributes

Attribute	Default	Description
data-site	required	Public site_id for the project.
data-api	`https://api.openanalyticsapi.com/collect`	Override the ingest endpoint (for self-hosted setups).
data-respect-dnt	`false`	If `"true"`, the snippet becomes a no-op when the browser sends Do Not Track.
data-replay-sample	`0.1`	Replay addon only. Probability that any given session is recorded. `0.1` means approximately 10% of eligible sessions. Set on the `oa-replay.js` script tag.

Addons (beta)

Two optional addons can be loaded after the core snippet. Each is hosted on the same domain, loads lazily, and respects the same oa('optOut') kill switch as the core tracker.

https://www.openanalyticsapi.com/sdk/oa-replay.js — rrweb-based session replay. PII masking on all <input>, <textarea>, and [data-oa-mask] by default. Pro+ plan required.
https://www.openanalyticsapi.com/sdk/oa-heatmap.js — click + scroll + attention heatmap collection. Pro+ plan required.

Collection is available in beta; beta viewers are available in the console under Replay and Heatmaps. Today's viewers show a privacy-safe event timeline (replay) and aggregated click hotspots + scroll-depth distribution (heatmaps); a full DOM-replay player and a page-overlay heatmap renderer are coming in a later beta release. Anything captured today is retained per your plan's retention setting.

Replay sampling

The replay addon records a configurable percentage of eligible sessions. The sampling decision is made once per session and persisted in sessionStorage so the choice is stable for that session.

HTML

<script async defer
  src="https://www.openanalyticsapi.com/sdk/oa-replay.js"
  data-site="YOUR_SITE_ID"
  data-replay-sample="0.1"></script>

data-replay-sample="0.1" means approximately 10% of eligible sessions. Use "1" to record every session (useful for staging or low-traffic sites); the default if you omit the attribute is also 0.1.

Self-hosting the snippet

You can download oa.js and serve it from your own domain (improves Core Web Vitals and bypasses some ad-blockers). The hosted version is exactly what we serve; no obfuscated keys or per-customer builds.

Source

The snippet is around 4 KB gzipped, has no third-party dependencies, and is safe to embed across customer sites. It does not call out to Google, Meta, or any cloud provider — only to api.openanalyticsapi.com/collect (or your configured endpoint).

← Quick Start REST API →