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 // 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
  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
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 — a token or email in ?.../#... never reaches analytics. trackQuery keeps the whole query, queryParams keeps only an allowlist, scrubUrl replaces the logic entirely.

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 and scrubUrl remain npm-only.

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

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/vskstudio/takt-core · npm @vskstudio/takt-core