Guide d'installation pour agents IA

Ce guide s’adresse à un agent IA (ou un script) à qui l’on a demandé d’installer Elvn sur un projet. Suivez les étapes dans l’ordre. Toute la documentation est disponible en Markdown brut sur /llms.txt (index) et /llms-full.txt (contenu complet).

Étape 0 — Prérequis (à demander à l’humain si absents)

Vous avez besoin de deux informations qui ne se devinent pas :

SITE_PUBLIC_ID — l’identifiant public du site, affiché dans le dashboard Elvn (Settings → Tracking du site). S’il n’existe pas encore, l’humain doit créer le site dans le dashboard avec le domaine de production exact (ex. www.exemple.fr).
Le domaine de production du projet. Il doit correspondre au domaine déclaré dans le dashboard (sous-domaines acceptés), sinon tous les événements seront silencieusement rejetés.

Ne fabriquez jamais un SITE_PUBLIC_ID. Si vous ne l’avez pas, arrêtez-vous et demandez-le.

Étape 1 — Le snippet à insérer

<script defer src="https://elvn.live/js/t.js" data-site="SITE_PUBLIC_ID"></script>

Règles :

L’insérer dans le <head> (idéalement juste avant </head>), sur toutes les pages du site — donc dans le layout/template global.
Une seule occurrence par page. Avant d’insérer, vérifiez qu’aucun snippet Elvn n’est déjà présent : grep -rn "elvn.live/js/t.js\|data-site" . (hors node_modules).
Ne pas ajouter async : defer suffit et préserve l’ordre.

Étape 2 — Détecter le framework et insérer

Détectez le framework par la présence de fichiers, dans cet ordre, et appliquez la variante correspondante.

Next.js (`next.config.*` présent)

App Router (app/layout.tsx ou .jsx) — utilisez next/script :

import Script from "next/script";

// dans le JSX de RootLayout, à l'intérieur de <html> :
<Script defer src="https://elvn.live/js/t.js" data-site="SITE_PUBLIC_ID" strategy="afterInteractive" />

Pages Router (pages/_document.tsx ou à défaut pages/_app.tsx) : balise <script defer …> dans le <Head> de _document, ou next/script dans _app.

Nuxt (`nuxt.config.*` présent)

Dans nuxt.config.ts :

export default defineNuxtConfig({
  app: {
    head: {
      script: [{ src: "https://elvn.live/js/t.js", defer: true, "data-site": "SITE_PUBLIC_ID" }],
    },
  },
});

Astro (`astro.config.*` présent)

Dans le layout partagé (ex. src/layouts/Layout.astro), dans le <head> :

<script is:inline defer src="https://elvn.live/js/t.js" data-site="SITE_PUBLIC_ID"></script>

is:inline empêche Astro de bundler/déplacer le script (les attributs data-* doivent rester sur la balise).

SvelteKit (`svelte.config.*` présent)

Dans src/app.html, avant </head> :

<script defer src="https://elvn.live/js/t.js" data-site="SITE_PUBLIC_ID"></script>

SPA Vite/CRA (React, Vue, Svelte sans SSR — `index.html` à la racine ou dans `public/`)

Dans le index.html du projet, avant </head> (même snippet que SvelteKit).

WordPress / PHP

Dans le template d’en-tête (header.php du thème, ou via un plugin d’insertion de code), avant </head> (même snippet).

HTML statique (aucun framework détecté)

Dans chaque fichier .html servi, avant </head> (même snippet).

Étape 3 — Options selon le contexte

SPA : activé par défaut, rien à faire (les navigations pushState/replaceState/popstate sont suivies). N’ajoutez data-spa="off" que sur demande explicite.
Adblockers / proxy first-party : si l’humain le demande, suivez Proxy first-party et utilisez src="/stats/t.js" data-api="/stats/e" à la place des URLs elvn.live.
Test local : le tracker est muet sur localhost. Pour tester en local uniquement, ajoutez temporairement l’attribut data-dev — et retirez-le avant commit/production.
CSP : si le projet définit une Content Security Policy, ajoutez https://elvn.live à script-src et à connect-src.
Événements custom : uniquement sur demande — voir Événements & goals. Jamais de donnée personnelle dans les props.
Bandeau cookies : n’en ajoutez pas pour Elvn (aucun cookie, exemption CNIL). Ne conditionnez pas le chargement du script à un consentement.

Étape 4 — Checklist de vérification

Exécutez dans l’ordre. Les étapes 1 à 3 sont automatisables ; la 4 exige l’humain ou un déploiement réel.

# 1. Le script Elvn est joignable (attendu : HTTP/2 200, content-type text/javascript, ETag)
curl -sI https://elvn.live/js/t.js | head -5

# 2. L'endpoint de collecte répond (attendu : 202 — ATTENTION : 202 ne signifie
#    PAS que l'événement est compté ; l'endpoint répond 202 même aux payloads
#    rejetés, par design)
curl -s -o /dev/null -w "%{http_code}\n" -X POST https://elvn.live/api/e --data '{}'

# 3. Le snippet est présent exactement une fois dans le HTML produit
#    (adapter la commande de build/serve au projet)
grep -c "data-site=\"SITE_PUBLIC_ID\"" <fichier-ou-sortie-html>   # attendu : 1

Vérification finale (la seule qui fasse foi) : déployer, visiter une page depuis le domaine de production, puis constater dans le dashboard Elvn que Settings → Tracking passe au vert et que la visite apparaît dans Realtime (~30-60 s de latence). Si rien n’apparaît alors que le POST /api/e part bien en 202, la cause la plus probable est un domaine visité différent du domaine déclaré dans le dashboard — demandez à l’humain de vérifier.

Pièges connus

Symptôme	Cause probable	Correction
Aucune requête `POST /api/e` ne part	Test sur localhost sans `data-dev` ; ou page en iframe ; ou navigateur automatisé (`navigator.webdriver`)	Tester depuis le domaine réel, hors iframe, dans un navigateur normal
`POST /api/e` part en 202 mais rien dans Realtime	Domaine visité ≠ domaine déclaré ; `data-site` erroné ; signal GPC actif ; adblocker sur `t.js`	Vérifier le domaine du site dans le dashboard, l’ID, désactiver GPC/adblock pour le test
Le script ne charge pas (bloqué)	Adblocker	Proxy first-party
Événement custom jamais reçu	Nom invalide (majuscules, espaces, accents) — abandonné en silence	Nom conforme à `/^[a-z0-9_-]{1,64}$/`, props plates et scalaires
Double comptage	Snippet inséré deux fois (layout + page)	Une seule occurrence