# SDK web (navigateur)

URL: https://traqio.app/fr/docs/sdks/web
Last updated: 2026-10-16

Ajouter Traqio à un site : @traqio/web garde le click id de la pub, de l’URL d’arrivée à la conversion, en stockage first-party. React, Vue, Angular, HTML.

`@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](https://traqio.app/fr/docs/concepts/attribution), 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](https://traqio.app/fr/docs/concepts/tracking-links) dont la destination est une page du site, pour que le trackID arrive dans l’URL.

## Mise en place

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

### Installer le paquet

```bash
npm install @traqio/web
```

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

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

### Initialiser sur chaque page

React / Next.js:
```tsx
// 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;
}
```

Vue / Nuxt:
```ts
// main.ts (Vue) — or plugins/traqio.client.ts in Nuxt
import { createProduct } from "vue";
import { Traqio } from "@traqio/web";
import App from "./App.vue";

void Traqio.init({ sdkKey: import.meta.env.VITE_TRAQIO_WEB_KEY });
createProduct(App).mount("#app");
```

Angular:
```ts
// app.config.ts
import { ApplicationConfig, PLATFORM_ID, inject, provideAppInitializer } from "@angular/core";
import { isPlatformBrowser } from "@angular/common";
import { Traqio } from "@traqio/web";

export const appConfig: ApplicationConfig = {
  providers: [
    provideAppInitializer(() => {
      if (isPlatformBrowser(inject(PLATFORM_ID))) void Traqio.init({ sdkKey: "YOUR_WEB_KEY" });
    }),
  ],
};
```

JavaScript:
```ts
import { Traqio } from "@traqio/web";

Traqio.init({ sdkKey: "YOUR_WEB_KEY" }); // tq_web_… — a WEB key, not the app key
```

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.

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

```ts
// 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é :

```xml
<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](https://traqio.app/fr/docs/sdks/node), [PHP / Laravel](https://traqio.app/fr/docs/sdks/php) ou [Python](https://traqio.app/fr/docs/sdks/python) — qui la rattache au clic.

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

```ts
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](https://traqio.app/fr/docs/concepts/events-and-revenue) : suivez les étapes qui comptent, pas chaque page vue.

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

|  | Aujourd’hui |
| --- | --- |
| Lire et garder le trackID (localStorage + cookie first-party) | Oui |
| Le partager entre les sous-domaines d’un même site | Oui, par le cookie |
| Événements avec valeur, devise et id de paiement | Oui — enregistrés, non attribués à une campagne |
| Visites (rétention) | Oui |
| Consentement, stockage seulement après accord, effacement | Oui |
| Rattacher une inscription à son clic | Oui — par votre backend, via un SDK serveur |
| Afficher les conversions web dans les rapports de la console | Oui — par campagne, à côté des installations, une fois l’inscription liée par votre backend |
| Envoyer les événements web à Meta ou TikTok | Pas encore |

**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](https://traqio.app/fr/docs/concepts/web-attribution#server). 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.

> **Les événements web ne touchent jamais les chiffres de vos apps** Un événement envoyé avec une clé web n’est jamais rattaché à une installation d’app, même quand son id utilisateur en désigne une : vos installations, revenus et ROAS mobiles restent exactement ce que les apps remontent.

## Consentement

```ts
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é](https://traqio.app/fr/docs/concepts/privacy).

## Référence de l’API

WebInitOptions:
```ts
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
}
```

| Méthode | Ce qu’elle fait |
| --- | --- |
| init(options) | Lit le trackID dans l’URL, puis démarre le SDK. Idempotent ; sans effet sur un serveur. |
| track(name, props?) | Met un événement en file : value, currency, transactionId, store. |
| setUserId(id) | Votre id utilisateur, après la connexion. |
| getTrackId() | Le trackID gardé, ou null s’il n’y en a pas ou s’il a expiré. |
| setConsent(granted) | Consentement au partage ; avec waitForConsent, décide aussi si quoi que ce soit peut être stocké. |
| forgetMe() | Effacement : le serveur supprime ce qu’il détient sur ce navigateur et cet utilisateur, le SDK se tait et oublie le trackID. |
| flush() | Envoie la file maintenant. Déjà branché sur le masquage de l’onglet et la sortie de page. |

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

> **Niveau de preuve** Le paquet est testé contre un navigateur simulé, vérifié et construit en CI ; il n’a pas encore tourné sur un site en production.

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