takt

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)

AttributeEffectDefault
data-domainSite identifier in your dashboardlocation.hostname
data-script-originFirst-party origin to derive the endpoint from ({origin}/api/event)https://taktlytics.com
data-endpointEvent ingestion endpoint (wins over data-script-origin)https://taktlytics.com/api/event
data-exclude-localhost="false"Also measures localhost / private IPsexcluded
data-enabled="false"Kill-switch: the tracker does nothingenabled
data-respect-dnt="false"Opt out of the client-side Do Not Track guard (the DNT and GPC headers are still dropped at ingestion)respected
data-sample-rate="0.5"Send only this fraction (0 to 1) of events1 (all)
data-track-queryKeep the full query string and hashstripped
data-query-params="utm_source,utm_medium"Keep only these query paramsnone

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-script-origin / data-endpoint: by default, events are posted to https://taktlytics.com/api/event. data-script-origin replaces the origin the endpoint is derived from ({origin}/api/event) when you serve Takt from your own domain; data-endpoint sets the full URL and wins over data-script-origin. For a first-party proxy served on the same origin as your page, pass data-endpoint="/api/event" explicitly. See First-party proxy.
  • Automatic capture (outbound clicks, downloads, HTML-declared events and 404s) is not part of the minimal snippet: they live in the takt.auto.js bundle and are enabled through data-auto (see below).
  • data-exclude-localhost: enabled by default. Pass "false" to also measure localhost and private IPs.
  • data-enabled="false" is a total kill-switch: no listener is attached and nothing is ever sent.
  • Privacy & sampling: the snippet respects Do Not Track and Global Privacy Control (Sec-GPC header / navigator.globalPrivacyControl) and strips the query string by default. Tune these on the tag itself: data-respect-dnt="false" (opt out of the client-side DNT guard; the DNT and GPC headers are still dropped at ingestion), 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-query-params="utm_source,utm_medium"
></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.

Automatic capture (data-auto)

The minimal takt.js snippet only measures pageviews. Automatic capture (outbound clicks, downloads, HTML-declared events and 404s) lives in the takt.auto.js bundle and is entirely opt-in through the data-auto attribute, which takes a comma-separated list.

AttributeEffectDefault
data-auto="outbound"Emits Outbound Link: Click on clicks to another domainoff
data-auto="downloads"Emits File Download on links pointing at a fileoff
data-auto="tagged"Emits the events declared on [data-takt-event] elementsoff
data-auto="404"Emits a 404 event on error pagesoff
data-downloads-ext="pdf,csv,epub"Restricts which extensions count as a downloaddefault list
data-redact-routes="/verify/[token],/reset/[code]"Sends the pattern instead of the real path of the listed routes: pageview, SPA navigation, 404 path and the destination of outbound clicks and downloads (see Route redaction)none
data-redact-undecodable-paths="false"Matches unreadable paths against the routes instead of /[redacted] (see Unreadable paths)masked
<script
  defer
  src="https://cdn.jsdelivr.net/npm/@vskstudio/takt-core/dist/takt.auto.js"
  data-domain="example.com"
  data-auto="outbound,downloads,tagged,404"
></script>
Without data-auto, takt.auto.js behaves exactly like takt.js: a single pageview, nothing more. Every attribute from the previous table still applies to this bundle. Each capture is detailed in Automatic extensions.

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
  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.

With neither endpoint nor scriptOrigin, events are posted to https://taktlytics.com/api/event. Pass endpoint: '/api/event' if you proxy Takt on the same origin as your page, or scriptOrigin: 'https://example.com/_takt' to derive the endpoint from another origin.

Advanced options

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

OptionTypeDefaultRole
enabledbooleantrueStops all sending when false (handy in staging)
debugbooleanfalseLogs every event to the console (npm-only)
sampleRatenumber1Samples sent events (0 to 1)
trackQuerybooleanfalseKeeps the query string as-is
queryParamsstring[]noneAllowlist of query params to keep
scrubUrl(url) => urlnoneCustom URL scrubbing, applied to the page, the referrer and the url of Outbound Link: Click and File Download events, and the path of 404 events (npm-only)
excludestring[]nonePath prefixes never tracked, e.g. ['/app', '/account'] (segment-bounded, checked at send time; npm-only)
redactRoutesstring[]noneSensitive route patterns sent instead of the real path, e.g. ['/verify/[token]'] sends /verify/[token] instead of /verify/abc123 (data-redact-routes on takt.auto.js, since 0.10.0)
redactUndecodablePathsbooleantrueUnreadable path (malformed % escape, invalid UTF-8): /[redacted] as soon as a route is configured; false matches it against the routes like any other, see Unreadable paths (since 0.12.0)
routeTemplatesbooleanfalseSends every page as its route template (/blog/[slug]); needs routeTemplate (npm-only, since 0.10.0)
routeTemplate() => string \| nullnoneReturns the current route template, read when routeTemplates is on; the framework wrappers provide it (npm-only, since 0.10.0)
taggedbooleanfalseCustom events from [data-takt-event] elements (snippet: data-auto="tagged")
notFoundbooleanfalseReports a 404 event on error pages (snippet: data-auto="404")

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. See Privacy.

The path, however, is sent as is: /verify/abc123 leaks the token. redactRoutes replaces the path of the listed routes with their pattern, and routeTemplates sends every page as a template, at the cost of per-page stats on a public site. The minimal takt.js snippet does not support them, and takt.auto.js only offers redactRoutes, through data-redact-routes. See Route redaction.

Name mapping: data-exclude-localhost → excludeLocalhost, data-script-origin → scriptOrigin, data-downloads-ext → fileExtensions. The semantics are identical between snippet and npm for the shared settings.