Configuration

Configuration

Takt is configured in two equivalent ways: via data-* attributes on the snippet tag (CDN), or via init() options (npm). Both drive the same settings.

data-* options (snippet)

Attribute	Effect	Default
data-domain	Site identifier in your dashboard	location.hostname
data-endpoint	Event ingestion endpoint	/api/event
data-outbound	Tracks clicks on outbound links (flag)	off
data-files	Tracks file downloads (flag)	off
data-exclude-localhost="false"	Also measures localhost / private IPs	excluded
data-enabled="false"	Kill-switch — the tracker does nothing	enabled
data-respect-dnt="false"	Opt out of the Do Not Track guard	respected
data-sample-rate="0.5"	Send only this fraction (0–1) of events	1 (all)
data-track-query	Keep the full query string and hash	stripped
data-query-params="utm_source,utm_medium"	Keep only these query params	none

Settings in detail

• data-domain — always set it explicitly. Without it, Takt infers the domain from location.hostname, which breaks aggregation if your site responds on several hosts (www, staging, test domain).
• data-endpoint — changes the URL events are posted to. Useful behind a proxy or a dedicated ingestion subdomain.
• data-outbound / data-files — these are flags: their mere presence activates them, regardless of value. Just write data-outbound (no need for ="true").
• data-exclude-localhost — enabled by default. Pass "false" to also measure localhost and private IPs.
• data-enabled="false" — total kill-switch: no listener is attached and nothing is ever sent.
• Privacy & sampling — the snippet respects Do Not Track and strips the query string by default. Tune these on the tag itself: data-respect-dnt="false" (opt out of the DNT guard), data-sample-rate="0.5" (send a fraction of events), data-track-query (keep the full query + hash), data-query-params="utm_source,utm_medium" (keep only an allowlist). Same semantics as the npm options below.

<script
  defer
  src="https://cdn.jsdelivr.net/npm/@vskstudio/takt-core/dist/takt.js"
  data-domain="example.com"
  data-outbound
  data-files
></script>

The data-exclude-localhost flag protects your visitors' privacy, and the snippet always respects Do Not Track. Only disable these guardrails if you know exactly why.

init() options (npm)

In the npm version, these same settings are passed as an object to init() (in camelCase for booleans):

import { init } from '@vskstudio/takt-core'

init({
  domain: 'example.com',    // required in practice
  endpoint: '/api/event',   // optional
  outbound: true,           // tracks outbound links
  files: true,              // tracks downloads
  excludeLocalhost: true,   // default
  respectDnt: true          // default
})

init() creates a shared instance, fires an automatic pageview and wires up SPA navigation. Call it only once, at application startup.

Advanced options

These tune privacy, sampling and autocapture. enabled, sampleRate, trackQuery and queryParams also have a snippet data-* form (above); debug, scrubUrl, exclude, redactRoutes, routeTemplates and routeTemplate are npm-only (the ≤ 1 kB minimal snippet does not carry them).

Option	Type	Default	Role
enabled	boolean	true	Stops all sending when false (handy in staging)
debug	boolean	false	Logs every event to the console (npm-only)
sampleRate	number	1	Samples sent events (0–1)
trackQuery	boolean	false	Keeps the query string as-is
queryParams	string[]	—	Allowlist of query params to keep
scrubUrl	(url) => url	—	Custom URL scrubbing, applied to the page URL, the referrer and the url prop of outbound-link and file-download events (npm-only)
exclude	string[]	—	Path prefixes never tracked, e.g. ['/app', '/account'] (segment-bounded, checked at send time; npm-only)
tagged	boolean	false	Custom events from data-takt-event elements (snippet: data-auto="tagged")
redactRoutes	string[]	none	Route patterns sent in place of the real path, e.g. ['/verify/[token]'] (since 0.10.0, npm-only)
routeTemplates	boolean	false	Sends every page as its route template (/blog/[slug]) instead of the real path; needs routeTemplate (since 0.10.0, npm-only)
routeTemplate	() => string | null	none	Returns the current route template; the framework wrappers wire it from their router (since 0.10.0, npm-only)

By default, the query string and hash are stripped from every URL before sending. trackQuery/queryParams/scrubUrl (npm) or data-track-query/data-query-params (snippet) tune it. Since 0.9.0, scrubUrl also receives the url prop of Outbound Link: Click and File Download events (origin and path). See Privacy.

The same trackQuery, queryParams and scrubUrl options exist on the Node client, see Server-side (Node).

Route redaction

Stripping the query does not touch the path: /verify/abc123 is sent as is. Since 0.10.0, two options replace real paths with route patterns:

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

• redactRoutes lists the sensitive routes. A matching path is sent as the pattern (/verify/[token]); every other page keeps its real path, so per-page stats stay intact.
• routeTemplates: true sends every page as its route template (/blog/hello becomes /blog/[slug]). It needs a routeTemplate resolver: the core does not know your router, the framework wrappers provide it. Suited to a private app, it merges every article of a public site into a single row.

Semantics, pattern syntax and the trade-off are detailed in Privacy. The Node client accepts redactRoutes too, plus a per-call route, see Server-side (Node).

Name mapping: data-exclude-localhost → excludeLocalhost. The semantics are identical between snippet and npm for the shared settings.

---

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