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 // custom URL scrubbing
  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

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()

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

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