JavaScript SDK reference — Docs

Everything below is on the default export of oakdata-js. Import it once and call methods anywhere — calls made before init() are queued and replayed when the tracker boots, so ordering never matters.

import

import oak from 'oakdata-js'

oak.init(key, options)

Boots the tracker. Call it once with your project key. Returns the live API instance (also stored on window.oak), or null during SSR / prerender. Calling init twice is a no-op — the first call wins.

init

oak.init(process.env.NEXT_PUBLIC_OAK_KEY!, {
  api_host: process.env.NEXT_PUBLIC_OAK_HOST,
})

The options object accepts:

Option	Type	Description
`api_host`	`string`	Base URL events are sent to. Defaults to the current origin — set it to your OakData host, e.g. `https://oakdata.co`.
`autocapture`	`boolean`	Autocapture clicks, form submits, input changes, and copies. Default `true`. See autocapture.
`capture_pageview`	`boolean`	Automatically fire `$pageview` on load and on every client-side route change. Default `true`.
`respect_dnt`	`boolean`	Honor the browser's Do Not Track signal. When `true` and DNT is enabled, the tracker disables itself entirely. Default `false`.
`property_denylist`	`string[]`	Property keys stripped from every event before it's sent — useful for scrubbing PII or noisy fields. Default `[]`.
`before_send`	`fn \| fn[]`	A hook (or array of hooks) run on each event just before it's queued. Return the event to send it, or `null`/`false` to drop it. Hooks run in order; the first to drop wins.
`loaded`	`(oak) => void`	Called once, after the tracker is fully wired up.
`debug`	`boolean`	Log internal activity to the console. Default `false`.

before_send example

Drop events from a noisy path and redact a property:

before_send

oak.init(KEY, {
  before_send: (event) => {
    if (event.context.page.path.startsWith('/admin')) return null
    if (event.properties.email) event.properties.email = '[redacted]'
    return event
  },
})

Capturing events

oak.capture(name, properties?)

Records a custom event. oak.track() is an exact alias. Event names are free-form strings; properties are any JSON-serializable object.

capture

oak.capture('signup_completed', { plan: 'pro', seats: 5 })

oak.page(properties?)

Manually records a $pageview. You rarely need this — with capture_pageview on (the default), pageviews fire automatically on load and on route changes. Use it for virtual pageviews, e.g. a modal you treat as a screen.

page

oak.page({ section: 'onboarding' })

Identity

Read the identity resolution guide for how anonymous and identified activity are stitched together.

oak.identify(userId, traits?)

Associates the current anonymous visitor with a known user id, linking their prior anonymous activity to the identified profile. Optionally pass traits to set in the same call. After identify, getDistinctId() returns the user id.

identify

oak.identify('user_8f3a', { email: 'sam@acme.com', plan: 'pro' })

oak.alias(newId)

Records an alias linking the current distinct id to newIdand switches the stored id to it. Use it to merge two ids you control (for example, tying a server-generated id to the browser's anonymous id).

alias

oak.alias('user_8f3a')

oak.set(traits) / oak.setOnce(traits)

Sets persistent traits on the current person. set overwrites existing keys; setOnceonly writes keys that aren't already present (good for first-touch attributes like signup date).

set

oak.set({ plan: 'enterprise' })
oak.setOnce({ first_seen_plan: 'free', signup_source: 'docs' })

Super properties

Super properties are merged into every subsequent event and persisted in local storage, so they survive reloads.

oak.register(props) / oak.unregister(key)

oak.register({ app_version: '2.4.0', workspace: 'acme' })
oak.unregister('workspace')

Groups

oak.group(type, id, traits?)

Associates the current person with a group — an account, company, organization, or any other entity many users share. Subsequent events carry the group association.

group

oak.group('company', 'acme-co', { name: 'Acme', plan: 'enterprise' })

Consent & lifecycle

oak.reset()

Clears all stored ids, traits, super properties, groups, and the queued event buffer, then generates a fresh anonymous id. Call it on sign-outso the next visitor on a shared device isn't attributed to the previous user.

reset

oak.reset()

oak.opt_out() / oak.opt_in()

opt_out() stops all sending, clears the pending queue, and persists the choice so it survives reloads. opt_in() re- enables tracking. Use these to back a cookie/consent banner.

consent

if (userDeclinedAnalytics) oak.opt_out()
else oak.opt_in()

oak.flush(useBeacon?)

Forces the queued events to send immediately rather than waiting for the next batch interval. Returns a promise. Pass true to use navigator.sendBeacon, which survives page unload (the SDK already does this internally on pagehide).

flush

await oak.flush()

Getters

Method	Type	Description
`oak.getDistinctId()`	`string \| null`	The current distinct id — the identified user id once identify() has run, otherwise the anonymous id. null before init().
`oak.getSessionId()`	`string \| null`	The current session id. null before `init()`.

The instance returned by oak.init() (and window.oak after boot) additionally exposes getFirstTouch() and getLastTouch()for the visitor's first- and last-touch attribution.

Autocaptured events

With autocapture and capture_pageview on, the SDK emits these without any code from you:

Event	Type	Description
`$pageview`	`auto`	Page load + SPA route change.
`$click`	`auto`	Any click, with the resolved actionable element.
`$rage_click`	`auto`	Three or more rapid clicks in the same spot.
`$dead_click`	`auto`	A click that produced no DOM change or navigation.
`$outbound_click`	`auto`	A click on a link to another host.
`$form_submit`	`auto`	A form submission (password fields excluded).
`$input_change`	`auto`	An input/select/textarea value change (value masked by default).
`$copy`	`auto`	Text copied to the clipboard.

See autocapture & data attributes for how to opt elements in or out, and events & properties for the properties attached to every event.

Performance & error events

The SDK also watches page performance and uncaught errors out of the box — no setup, and independent of autocapture. These surface production regressions (a Core Web Vital that slipped, an error spiking on one route) right alongside behavioural data.

Event	Type	Description
`$web_vital`	`auto`	A Core Web Vital reading — `LCP`, `INP`, or `CLS`— reported as it's finalized for the page.
`$error`	`auto`	An uncaught JavaScript error, with its message, source, and stack.
`$unhandled_rejection`	`auto`	A promise rejection with no handler.

Errored sessions are flagged so they stand out in the sessions and replaylists, making it easy to jump from “something broke” to the exact recording.