Documentation Analytique Intlayer

@intlayer/analytics est un package compagnon optionnel qui vous indique quel contenu est réellement affiché à vos visiteurs — quelle page, dans quelle locale, et quel élément de contenu traduit spécifique — afin que vous puissiez comprendre votre audience et exécuter des tests A/B sur le contenu.

Table des matières

Ce qu'il suit

@intlayer/analytics regroupe trois types d'événements anonymes en lots :

Les événements sont collectés en mémoire et envoyés sous forme d'une seule requête groupée (batch) environ toutes les 20 secondes — jamais à chaque frappe au clavier ou rendu — donc l'analytique n'impacte jamais le temps de premier rendu et n'ajoute pas une requête par interaction.

Comment cela propulse les tests A/B sur le contenu

Intlayer vous permet déjà de déclarer des Variantes de contenu (par exemple un dictionnaire hero-banner avec une variante control et une variante black_friday). @intlayer/analytics boucle la boucle :

1. getVariant(experimentKey, variants) attribue de manière déterministe chaque session anonyme à une variante — une fonction pure de l'ID de session et de la clé d'expérience, donc l'attribution est stable dans toute la session et ne nécessite aucun aller-retour serveur avant le premier rendu (pas de scintillement, pas de décalage de mise en page).
2. Chaque événement content_exposure transporte la variant qui a été affichée.
3. useConversion() vous permet d'attribuer un objectif (par exemple "cta_click") à cette variante.
4. L'endpoint des résultats d'expérience du tableau de bord compare les taux de conversion par variante, y compris la signification statistique (un test z).

Installation

@intlayer/analytics est une dépendance peer, optionnelle — jamais installée automatiquement par un package de framework. Ajoutez-la aux côtés de intlayer :

npm install @intlayer/analytics

Si vous ne l'installez pas, chaque point d'intégration se résout en une opération vide (no-op) — voir Zéro coût quand non installé ci-dessous.

Configuration

Analytics réutilise le bloc de configuration editor existant — il n'y a pas de schéma de configuration analytics séparé à remplir :

import type { IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  editor: {
    backendURL: "https://back.intlayer.org", // Également utilisé comme endpoint d'ingestion d'analytique
    clientId: "your-client-id", // Aussi utilisé comme clé de projet analytique
    clientSecret: "your-client-secret",
  },
};

export default config;

• editor.backendURL — l'URL de base vers laquelle les événements analytiques sont envoyés (POST {backendURL}/api/analytics/events).
• editor.clientId — la clé de projet publique attribuée à chaque événement ingéré. Elle agit également comme interrupteur d'activation : l'analytique reste complètement désactivée (et éliminée du code par tree-shaking, voir ci-dessous) jusqu'à ce que clientId soit configuré.

Si vous auto-hébergez (self-host) Intlayer, l'analytique pointe automatiquement vers votre propre instance puisqu'elle partage editor.backendURL.

Support des frameworks

Analytics est intégré dans le IntlayerProvider partagé de react-intlayer, il est donc disponible dès aujourd'hui partout où ce provider est utilisé :

Utilisation

Suivi automatique au niveau du provider

Aucune modification de code n'est requise. Une fois que @intlayer/analytics est installé et que editor.clientId est configuré, IntlayerProvider effectue automatiquement les actions suivantes :

• initialise le client d'analytique au montage (mount),
• enregistre un page_view au chargement initial,
• enregistre un page_view à chaque changement de locale,
• démarre la boucle de flush d'environ 20s et vide tous les événements restants au démontage / fermeture d'onglet (via navigator.sendBeacon, avec un repli vers fetch(..., { keepalive: true })).

Suivi automatique au niveau des nœuds

Chaque fois que useIntlayer résout un élément de contenu pour l'affichage, l'interpréteur signale un événement content_exposure pour ce(tte) dictionaryKey + chemin de clé + locale exacte — là encore, aucune modification de code n'est requise. Les expositions répétées du même nœud dans une fenêtre de flush sont fusionnées en un seul événement avec un count, donc une liste qui se re-rend 50 fois n'envoie pas 50 événements.

Suivi des conversions pour les tests A/B

Utilisez useConversion() pour attribuer un objectif à la variante qu'une session a vue :

Résolution d'une variante côté client

Confidentialité & performance

• Anonyme par conception : les sessions sont identifiées par un ID rotatif ; le backend ne stocke jamais qu'un hash SHA-256 de cet ID — jamais l'ID brut, jamais une adresse IP.
• La localisation est approximative (coarse) : uniquement un code pays, dérivé des en-têtes de géolocalisation CDN (cf-ipcountry, x-vercel-ip-country, …) — aucune IP n'est lue ou stockée.
• Les URL excluent les paramètres de recherche par défaut, les chaînes de requête (query strings) ne sont donc jamais capturées.
• Échantillonnage (Sampling) : sampleRate vous permet de conserver seulement une fraction des événements d'exposition de contenu sur les applications à fort trafic.
• En lots (Batched) : une requête environ toutes les 20 secondes (flushInterval), ou plus tôt si le tampon se remplit (maxBufferSize) — jamais une requête par événement.

Zéro coût quand non installé

@intlayer/analytics suit exactement le même modèle de dépendance optionnelle que @intlayer/editor :

• chaque point d'intégration charge le package via un import() dynamique enveloppé dans un try/catch — une application qui n'installe jamais @intlayer/analytics ne paie aucun coût en taille de bundle ou à l'exécution, et ne voit jamais d'erreur ;
• une variable d'environnement au moment de la compilation (INTLAYER_ANALYTICS_ENABLED), définie automatiquement à 'false' par @intlayer/config chaque fois que editor.clientId n'est pas configuré, permet aux bundlers d'éliminer le code mort (dead-code-eliminate) de toute l'intégration ;
• l'analytique est désactivée à l'intérieur de l'iframe de prévisualisation de l'éditeur/CMS Intlayer, afin que les sessions d'éditeur ne soient jamais comptées comme du vrai trafic.

Tableau de bord : Page Analytique

Une fois que votre projet a collecté des événements, la page Analytics dans le tableau de bord Intlayer (visible dans la barre latérale une fois qu'un projet est sélectionné) affiche :

• Utilisateurs actifs — visiteurs uniques sur la fenêtre glissante sélectionnée (7 / 30 / 90 jours).
• Utilisateurs aujourd'hui et utilisateurs au cours des 7 derniers jours.
• Pages vues sur la fenêtre sélectionnée.
• Un graphique d'évolution des visiteurs uniques quotidiens.
• Des onglets de répartition par Locales et par Emplacement (Location), classant votre audience par locale et par pays.

Référence API Backend

Tous les endpoints de lecture nécessitent une authentification ; l'ingestion est publique et attribuée par clientId dans le corps (body).

Vous pouvez également appeler ces endpoints de manière programmatique avec le SDK CMS :

import { createIntlayerCMS } from "@intlayer/api";import { analyticsEndpoint } from "@intlayer/api/analytics";const cms = createIntlayerCMS();const { data: audience } = await analyticsEndpoint(cms).getAudience(30);

Liens utiles

• Dictionnaires dynamiques - Collections et variantes
• Intlayer CMS - SDK CMS
• Éditeur Visuel Intlayer
• Référence de configuration
• Guide d'auto-hébergement (Self-Hosting)