Référence API

Surface publique du package @vskstudio/takt-core (intégration npm). Côté snippet, seule la fonction track est exposée. Voir la section Global window.takt en bas de page.

init(options)

Crée et stocke l’instance partagée, puis (par défaut) câble la navigation SPA et émet le pageview initial. À appeler une seule fois au démarrage. Retourne l’instance Analytics. init() est idempotent : un nouvel appel dispose proprement les écouteurs de l’instance précédente avant d’en recréer une.

function init(options?: {
  domain?: string
  endpoint?: string          // défaut: https://taktlytics.com/api/event
  scriptOrigin?: string      // origine dont dériver {origin}/api/event
  respectDnt?: boolean       // défaut: true
  excludeLocalhost?: boolean // défaut: true
  exclude?: string[]         // préfixes de chemin jamais suivis (borné au segment)
  enabled?: boolean          // défaut: true
  debug?: boolean            // défaut: false
  sampleRate?: number        // défaut: 1
  trackQuery?: boolean       // défaut: false (query + hash strippés)
  queryParams?: string[]     // allowlist de paramètres à conserver
  scrubUrl?: (url: string) => string // page, referrer, url des liens sortants et téléchargements
  redactRoutes?: string[]    // motifs de routes envoyés à la place du chemin réel
  redactUndecodablePaths?: boolean // vrai : chemin illisible masqué quand une route existe
  routeTemplates?: boolean   // défaut: false (chaque page envoyée en gabarit)
  routeTemplate?: () => string | null | undefined // gabarit de la route courante
  auto?: boolean             // défaut: true (pageview auto + SPA)
  outbound?: boolean         // défaut: false
  files?: boolean            // défaut: false
  fileExtensions?: string[]  // extensions suivies si files=true
  notFound?: boolean         // défaut: false (event 404 sur les pages d'erreur)
  tagged?: boolean           // défaut: false (events custom depuis data-takt-event)
}): Analytics

Le chemin, lui, part en clair. redactRoutes remplace le chemin des routes listées par leur motif (page, referrer interne, liens sortants et téléchargements, events 404). routeTemplates envoie toutes les pages en gabarit via le résolveur routeTemplate, que les wrappers de framework fournissent ; sur un site public, il fusionne tous les articles en une ligne. Quand le résolveur ne renvoie rien, redactRoutes s’applique quand même. Détails et syntaxe des motifs dans Masquage de routes.

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

track(name, options)

Émet un événement. Le nom pageview est réservé (utilise pageview()). Le type public de track() n’accepte que props :

function track(name: string, options?: { props?: Record<string, string> }): void

track('Signup', { props: { plan: 'pro' } })

Les valeurs de props sont des chaînes (les non-chaînes sont converties) ; une valeur vide ('', null, undefined) est ignorée. Les props sont plafonnées à 30 clés, clés ≤ 64 caractères, valeurs ≤ 1024 caractères ; au-delà, l’event part quand même et un avertissement console est émis une fois.

Pour attacher du revenue, passe par l’instance retournée par init() (dont la méthode track accepte revenue, avec un montant en chaîne). Le montant doit matcher \d+(\.\d{1,2})? et la devise être un code de 3 lettres, sinon le revenue est abandonné (avec avertissement) :

const takt = init({ domain: 'exemple.fr' })

takt.track('Purchase', {
  props: { plan: 'pro' },
  revenue: { amount: '29', currency: 'EUR' }
})

Le format exact envoyé sur le réseau est décrit dans Events & payload.

pageview()

Émet manuellement une page vue. Rarement nécessaire : init() suit déjà la navigation côté client : pushState, replaceState, popstate et hashchange déclenchent tous un pageview automatique.

function pageview(): void

optOut() / optIn() / isOptedOut()

Pilotent le consentement par visiteur. Le choix est persisté dans localStorage (takt_ignore).

function optOut(): void        // pose takt_ignore='1', aucun event envoyé
function optIn(): void         // retire le drapeau, reprend le tracking
function isOptedOut(): boolean // true si le visiteur a refusé la mesure

Ces trois fonctions n’ont besoin d’aucune instance : elles marchent avant init() (une bannière de consentement rendue en premier), et toute instance créée ensuite respecte le choix. Côté serveur, sans localStorage, elles ne font rien et isOptedOut() renvoie false. L’instance retournée par init() ou createTakt() expose les mêmes méthodes optOut(), optIn() et isOptedOut(), branchées sur le même état.

Voir Vie privée pour l’ordre exact des garde-fous.

Global window.takt

Côté snippet, seule la fonction track est exposée sur le global. Elle accepte props et revenue (montant en chaîne) :

window.takt('Signup', { props: { plan: 'pro' } })
window.takt('Purchase', { revenue: { amount: '29', currency: 'EUR' } })