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          // default: https://taktlytics.com/api/event
  scriptOrigin?: string      // origin to derive {origin}/api/event from
  respectDnt?: boolean       // default: true
  excludeLocalhost?: boolean // default: true
  exclude?: string[]         // path prefixes never tracked (segment-bounded)
  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
  redactRoutes?: string[]    // route patterns sent instead of the real path
  redactUndecodablePaths?: boolean // true: an unreadable path is masked when a route exists
  routeTemplates?: boolean   // default: false (every page sent as a 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
  notFound?: boolean         // default: false (404 event on error pages)
  tagged?: boolean           // default: false (custom events from data-takt-event)
}): Analytics

The path, however, is sent as is. redactRoutes replaces the path of the listed routes with their pattern (page, same-site referrer, outbound and download links, 404 events). routeTemplates sends every page as a template through the routeTemplate resolver, which the framework wrappers provide; on a public site, it merges every article into one row. When the resolver returns nothing, redactRoutes still applies. Details and pattern syntax in Route redaction.

init({ domain: 'example.com', redactRoutes: ['/verify/[token]', '/reset/:code'] })

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

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.

See Privacy for the exact order of the guardrails.

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' } })