API de la librairie

Méthodes

sarutobi.init(options): void

sarutobi.capture(name, props?): void    // event métier
sarutobi.track(name, props?): void      // alias de compatibilité
sarutobi.identify(id, props?): void     // relie l'activité à une personne
sarutobi.reset(): void                  // renouvelle identité anonyme et session
sarutobi.setConsent(state): void        // granted, denied ou pending
sarutobi.pageview(path?): void          // pageview manuel
sarutobi.flush(): void                  // vide la file immédiatement
sarutobi.setContext(props | null): void // props ajoutées à tous les events suivants
sarutobi.optOut(): void                 // arrête la collecte, mémorisé localement
sarutobi.optIn(): void
sarutobi.isOptedOut(): boolean

Aucune méthode ne renvoie de promesse et aucune ne fait attendre l'appelant. capture() retourne void, immédiatement. Toute la surface publique est enveloppée : si la plateforme est en panne, si le réseau tombe, si le navigateur est exotique, votre site continue de fonctionner exactement pareil. Une erreur de collecte n'est jamais une erreur applicative.

Options

Option	Type	Défaut	Description
projectToken	string	—	Requis. Fourni par le dashboard.
siteId	string	—	Alias de compatibilité de projectToken.
host	string	sarutobi.ascencia.re	Instance de collecte.
autoPageview	boolean	true	Pageview à l'init et à chaque changement d'URL.
trackDuration	boolean	true	Envoie un pageleave portant le temps passé.
trackVitals	boolean	true	Core Web Vitals.
trackErrors	boolean	true	window.onerror et unhandledrejection.
hashRouting	boolean	false	Traite le #hash comme faisant partie du chemin.
respectDnt	boolean	false	Ne collecte rien si navigator.doNotTrack vaut « 1 ».
excludePaths	string[]	[]	Motifs glob ignorés côté client.
enabled	boolean	true sauf localhost	Interrupteur général.
debug	boolean	false	Trace chaque event dans la console.
beforeSend	(e) => e \| null	—	Dernier filtre : modifie ou annule un event.
consent	granted \| denied \| pending	pending	État initial de collecte.
persistence	localStorage \| memory \| none	localStorage	Persistance de l'identité anonyme.
release	string	—	Version du produit instrumenté.
environment	string	—	Environnement : production, staging…

Identité

Le SDK crée un anonymous_id persistant et un identifiant de session. Après authentification, identify() rattache l'activité à l'identifiant métier. Appelez reset()à la déconnexion ou lors d'un changement de compte.

sarutobi.identify("user_42", { plan: "pro" });
sarutobi.reset();

Consentement

Le SDK démarre avec consent: "pending": aucun événement ni identifiant persistant n'est créé avant setConsent("granted"). Un refus efface l'identité locale.

setContext

Pour les dimensions transverses — locale, thème, version déployée. Les propriétés sont ajoutées à tous les events suivants.

sarutobi.setContext({ locale: "fr", theme: "dark", app_version: "1.4.2" });

Les appels successifs fusionnent ; setContext(null)réinitialise tout. Il n'existe pas de suppression clé par clé : nullest une valeur de propriété légitime, lui donner en plus le sens de « supprime cette clé » rendrait impossible d'en transmettre une.

beforeSend

Dernier filtre avant l'envoi. Renvoyez nullpour annuler l'event, ou une version modifiée. Utile comme garde défensif sur un site sensible.

beforeSend: (event) => {
  // Ne jamais laisser passer un chemin contenant un identifiant
  if (/\/profil\/[^/]+$/.test(new URL(event.u).pathname)) return null;
  return event;
}

Opt-out

optOut() écrit une clé sarutobi_opt_out en localStorage. Cette API historique équivaut désormais à un consentement refusé ; optIn() réactive la collecte avec une nouvelle identité.

Poids

Environ 3,6 ko gzip pour @sarutobi/js, 3,8 ko avec l'adaptateur React, zéro dépendance runtime. Le budget est une contrainte de CI : le build échoue au-delà.