API Reference

API reference

Public surface of the @vskstudio/takt-core package (npm integration). On the snippet side, only the track function is exposed — see the Global window.takt section at the bottom of the page.

init(options)

Creates and stores the shared instance, then (by default) wires up SPA navigation and emits the initial pageview. Call it only once at startup. Returns the Analytics instance. init() is idempotent: a new call cleanly disposes the previous instance's listeners before creating a new one.

function init(options?: {
  domain?: string
  endpoint?: string
  respectDnt?: boolean       // default: true
  excludeLocalhost?: boolean // default: true
  enabled?: boolean          // default: true
  debug?: boolean            // default: false
  sampleRate?: number        // default: 1
  trackQuery?: boolean       // default: false (query + hash stripped)
  queryParams?: string[]     // allowlist of params to keep
  scrubUrl?: (url: string) => string // page, referrer, url of outbound links and downloads
  exclude?: string[]         // path prefixes never tracked (segment-bounded)
  redactRoutes?: string[]    // route patterns sent in place of the real path
  routeTemplates?: boolean   // default: false (every page sent as its route template)
  routeTemplate?: () => string | null | undefined // current route template
  auto?: boolean             // default: true (auto pageview + SPA)
  outbound?: boolean         // default: false
  files?: boolean            // default: false
  fileExtensions?: string[]  // extensions tracked if files=true
  tagged?: boolean           // default: false (custom events from data-takt-event)
}): Analytics

Option	Type	Default	Role
domain	string	location.hostname	Site identifier
endpoint	string	/api/event	Ingestion URL
respectDnt	boolean	true	Respects Do Not Track
excludeLocalhost	boolean	true	Ignores localhost / private IPs
enabled	boolean	true	Stops all sending when false
debug	boolean	false	Logs every event to the console
sampleRate	number	1	Sampling (0–1) of sent events
trackQuery	boolean	false	Keeps the query string as-is
queryParams	string[]	—	Query params to keep (allowlist)
scrubUrl	(url) => url	—	Custom URL-scrubbing function, also applied to the url of Outbound Link: Click and File Download events
exclude	string[]	—	Path prefixes never tracked, e.g. ['/app','/account'] (segment-bounded)
redactRoutes	string[]	none	Route patterns (/verify/[token], /reset/:code) sent in place of the matching real path: page URL, internal referrer, own-origin link and download URLs, 404 path
routeTemplates	boolean	false	Sends every page as its route template; requires routeTemplate
routeTemplate	() => string | null	none	Resolver of the current route template, called at send time; the framework wrappers provide it
auto	boolean	true	Initial pageview + SPA tracking
outbound	boolean	false	Tracks outbound links
files	boolean	false	Tracks downloads
fileExtensions	string[]	pdf, zip, xlsx, docx, mp4	Tracked file extensions
tagged	boolean	false	Custom events from data-takt-event elements (snippet: data-auto="tagged")

By default, the query string and hash are stripped from every URL (page, referrer, outbound links) before sending, so a token or email in ?.../#... never reaches analytics. trackQuery keeps the whole query, queryParams keeps only an allowlist, scrubUrl replaces the logic entirely. Your function also receives the url property of Outbound Link: Click and File Download events (origin and path), so an identifier slipped into the path of an outbound link or a file can be masked too.

With the CDN snippet, init is done for you from the data-* attributes, including data-enabled, data-respect-dnt, data-sample-rate, data-track-query and data-query-params. Only debug, scrubUrl, exclude, redactRoutes, routeTemplates and routeTemplate remain npm-only.

The query and hash are stripped, but the path is sent as is. redactRoutes (since 0.10.0) masks the path of sensitive routes only; routeTemplates masks every path and merges the pages sharing a template. See Privacy.

track(name, options)

Emits an event. The name pageview is reserved (use pageview()). The public type of track() only accepts props:

function track(name: string, options?: { props?: Record<string, string> }): void

track('Signup', { props: { plan: 'pro' } })

props values are strings (non-strings are coerced); an empty value ('', null, undefined) is ignored. Props are capped at 30 keys, keys ≤ 64 characters, values ≤ 1024 characters; beyond that the event still sends and a console warning fires once.

To attach revenue, go through the instance returned by init() (whose track method accepts revenue, with the amount as a string). The amount must match \d+(\.\d{1,2})? and the currency be a 3-letter code, otherwise the revenue is dropped (with a warning):

const takt = init({ domain: 'example.com' })

takt.track('Purchase', {
  props: { plan: 'pro' },
  revenue: { amount: '29', currency: 'EUR' }
})

The exact format sent on the wire is described in Events & payload.

pageview()

Manually emits a pageview. Rarely needed: init() already tracks client-side navigation — pushState, replaceState, popstate and hashchange all trigger an automatic pageview.

function pageview(): void

optOut() / optIn() / isOptedOut()

Drive per-visitor consent. The choice is persisted in localStorage (takt_ignore).

function optOut(): void        // sets takt_ignore='1', no event sent
function optIn(): void         // removes the flag, resumes tracking
function isOptedOut(): boolean // true when the visitor refused measurement

Since 0.9.0, these three functions need no instance: they work before init() (a consent banner rendered first), and every instance created later honours the choice. On the server, without localStorage, they do nothing and isOptedOut() returns false. The instance returned by init() or createTakt() exposes the same optOut(), optIn() and isOptedOut() methods, backed by the same state.

import { init, isOptedOut, optIn, optOut } from '@vskstudio/takt-core'

const consentBannerNeeded = !isOptedOut()

function onConsentChoice(accepted: boolean) {
  if (accepted) optIn()
  else optOut()
}

init({ domain: 'example.com' })

See Privacy for the exact order of the guardrails.

@vskstudio/takt-core/server

A separate Node entry, createServerTakt(), sends pageviews and events server to server. It is documented on its own page: Server-side (Node).

Global window.takt

On the snippet side, only the track function is exposed on the global. It accepts props and revenue (amount as a string):

window.takt('Signup', { props: { plan: 'pro' } })
window.takt('Purchase', { revenue: { amount: '29', currency: 'EUR' } })

The global does not expose optOut/optIn/pageview. On the snippet side, opt-out is driven directly via localStorage (key takt_ignore) — see Privacy. The pageview is automatic (initial + SPA navigation).

---

Source: github.com/taktlytics/takt-core · npm @vskstudio/takt-core