SDK web (navigateur)

@traqio/web est le SDK Traqio pour les sites et les applications web. Quand un visiteur arrive depuis un lien de tracking Traqio, l’URL d’arrivée porte le click id de la publicité — le trackID — dans traq_click. Le SDK le lit, le garde en stockage first-party (localStorage, plus un cookie sur votre propre domaine) et le rend au moment où le visiteur convertit, pour que la conversion soit rattachée à son clic de façon déterministe, pas devinée. Il enregistre aussi les événements et les visites web, avec le consentement et l’effacement. Pas de fingerprinting, pas de cookie tiers, pas d’identifiant publicitaire ; environ 7 Ko gzippés, un seul paquet pour React, Vue, Angular et le HTML simple.

Prérequis#

• N’importe quel navigateur à jour (le SDK utilise fetch et localStorage).
• Une clé web pour le site. La clé d’une app mobile est refusée ici, et inversement.
• Des liens qui arrivent sur votre site : un lien de tracking dont la destination est une page du site, pour que le trackID arrive dans l’URL.

Mise en place#

1. Créer une clé web#

   Dans la console, ouvrez Intégrations → SDK pour le site et créez une clé web. Listez chaque origine qui exécute le SDK — schéma et hôte, sans chemin : https://example.com, https://www.example.com, https://app.example.com. Il n’y a pas de joker. Une requête venue de toute autre origine, ou sans en-tête Origin (curl, un serveur), est refusée en 403.

2. Installer le paquet#

   npm install @traqio/web

   Ou, sans étape de build, une balise sur chaque page — elle s’initialise seule et expose window.Traqio :

   <script src="https://cdn.jsdelivr.net/npm/@traqio/web@0.1/build/traqio.min.js"
           data-sdk-key="YOUR_WEB_KEY" async></script>

3. Initialiser sur chaque page#

   React / Next.jsVue / NuxtAngularJavaScript

   // app/traqio.tsx — mounted once, in the root layout
   "use client";
   import { useEffect } from "react";
   import { Traqio } from "@traqio/web";
   
   export function TraqioInit(): null {
     useEffect(() => {
       void Traqio.init({ sdkKey: process.env.NEXT_PUBLIC_TRAQIO_WEB_KEY! });
     }, []);
     return null;
   }

   Une fois, le plus tôt possible. init lit le trackID dans l’URL courante avant toute autre chose : un visiteur qui repart aussitôt le garde quand même. Sans risque en rendu côté serveur : sur un serveur, il ne fait rien.

4. Garder le trackID avec l’utilisateur#

   La conversion qui compte — une inscription, un abonnement, un achat — a le plus souvent lieu sur votre backend, là où l’id utilisateur est connu. Le SDK écrit le cookie traq_click sur votre domaine enregistrable (example.com) : votre backend le reçoit avec la requête d’inscription elle-même.

   // Node / Express — the browser sends the cookie with the sign-up request itself
   app.post("/signup", async (req, res) => {
     const trackId = req.cookies.traq_click ?? req.body.traq_click ?? null;
     const user = await users.create({ email: req.body.email, traqClick: trackId });
     // …
   });

   Si votre backend est sur un autre domaine, envoyez-le explicitement — Traqio.getTrackId() le renvoie, ou null quand le visiteur ne vient pas d’une publicité :

   <form id="signup" action="/signup" method="post">
     <input type="hidden" name="traq_click" />
     …
   </form>
   <script>
     // Filled at submit time, so it works whenever the SDK finished loading.
     document.getElementById("signup").addEventListener("submit", (e) => {
       e.target.elements.traq_click.value = window.Traqio?.getTrackId() ?? "";
     });
   </script>

   Votre backend signale ensuite l’inscription avec le trackID via un SDK serveur — Node.js, PHP / Laravel ou Python — qui la rattache au clic.

5. Suivre les événements et l’id utilisateur#

   Traqio.setUserId(user.id); // after sign-in
   
   Traqio.track("signup");
   Traqio.track("purchase", { value: 49, currency: "EUR", transactionId: payment.id, store: "stripe" });

   Les événements sont regroupés, renvoyés en cas d’échec, conservés d’une page à l’autre, et envoyés quand l’onglet est masqué ou la page quittée. Un événement suivi est une conversion : suivez les étapes qui comptent, pas chaque page vue.

Ce qu’il fait aujourd’hui, et ce qu’il ne fait pas#

Le SDK navigateur n’envoie jamais le trackID lui-même. Une clé que n’importe qui peut lire dans votre page ne doit pas pouvoir créditer une campagne : le lien entre une conversion et son clic est fait par votre backend, avec une clé serveur secrète, via un SDK serveur. Les événements que le navigateur envoie lui-même sont enregistrés sans campagne, et aucun événement web n’est encore transmis aux régies.

Consentement#

Traqio.init({ sdkKey: "YOUR_WEB_KEY", waitForConsent: true });

// when your consent banner gets an answer
consentBanner.onAnswer((granted) => Traqio.setConsent(granted));

Avec waitForConsent, rien n’est écrit sur l’appareil — ni localStorage, ni cookie — avant setConsent(true) ; le SDK fonctionne quand même pour la page courante, en mémoire. setConsent(true) stocke alors ce que la page avait gardé, trackID compris ; setConsent(false) supprime tout ce que le SDK avait stocké. La même réponse décide si les données de ce visiteur peuvent être partagées avec les régies — voir confidentialité.

Référence de l’API#

interface WebInitOptions {
  sdkKey: string;           // the site's web key (tq_web_…)
  endpoint?: string;        // default "https://api.traqio.app"
  userId?: string;          // your user id, once known
  consent?: boolean;        // ad-sharing consent, if already known
  waitForConsent?: boolean; // store nothing until setConsent(true) — default false
  trackIdDays?: number;     // how long the trackID is kept — default 30
  cookies?: boolean;        // false = localStorage only — default true
}

Limites#

• Safari garde 7 jours le stockage écrit en JavaScript sur les sites qu’il classe comme traqueurs : le trackID peut y expirer avant ce que dit trackIdDays.
• Un clic dans le navigateur intégré d’une app, suivi d’une conversion dans un autre navigateur sans connexion, ne porte aucun trackID : cette conversion est affichée non attribuée, jamais devinée.

Questions fréquentes#

Qu’est-ce que le trackID ?

Le click id de la publicité sur laquelle le visiteur a cliqué. Un lien de tracking Traqio l’ajoute à l’URL d’arrivée dans le paramètre traq_click ; @traqio/web le lit et le garde en stockage first-party (localStorage et un cookie sur votre propre domaine), pour que la conversion soit rattachée plus tard à ce clic précis au lieu d’être devinée.

La clé web est-elle un secret ?

Non. Elle est dans votre page, donc lisible par tous. Elle est protégée par sa liste d’origines autorisées : l’API Traqio ne l’accepte que depuis les origines déclarées, vérifiées sur l’en-tête Origin que le navigateur pose lui-même. Parce qu’elle est publique, une clé web ne peut pas attribuer une conversion à un clic — il faut pour cela une clé serveur secrète, utilisée par votre backend.

@traqio/web fonctionne-t-il avec le rendu côté serveur ?

Oui. Rien ne touche window ni document à l’import du module, et init() ne fait rien sur un serveur. Appelez-le depuis du code qui s’exécute dans le navigateur : un composant client, un plugin .client, ou un initializer protégé par isPlatformBrowser.

Combien de temps le trackID est-il gardé ?

30 jours par défaut (option trackIdDays). Le serveur applique de toute façon votre fenêtre d’attribution, donc le garder plus longtemps est sans effet. Safari limite à 7 jours le stockage écrit en JavaScript sur les sites qu’il classe comme traqueurs : comptez 7 jours là-bas.