Documentación de Intlayer Analytics

@intlayer/analytics es un paquete complementario opcional que te indica qué contenido se muestra realmente a tus visitantes — qué página, en qué configuración regional (locale) y qué fragmento específico de contenido traducido — para que puedas entender a tu audiencia y ejecutar pruebas A/B en el contenido.

Tabla de Contenidos

Qué rastrea

@intlayer/analytics agrupa tres tipos de eventos anónimos:

Los eventos se recopilan en memoria y se envían como una sola solicitud por lotes aproximadamente cada 20 segundos — nunca en cada pulsación de tecla o renderizado — por lo que la analítica nunca afecta el tiempo de primer renderizado ni añade una solicitud por cada interacción.

Cómo impulsa las pruebas A/B en el contenido

Intlayer ya te permite declarar Variantes de contenido (por ejemplo, un diccionario hero-banner con una variante control y una black_friday). @intlayer/analytics cierra el ciclo:

1. getVariant(experimentKey, variants) asigna de manera determinista cada sesión anónima a una variante — una función pura del id de sesión y la clave del experimento, por lo que la asignación es estable durante toda la sesión y no requiere ida y vuelta al servidor antes del primer renderizado (sin parpadeos, sin cambios de diseño).
2. Cada evento de content_exposure lleva la variant que se mostró.
3. useConversion() te permite atribuir un objetivo (por ejemplo, "cta_click") a esa variante.
4. El endpoint de resultados de experimentos del panel de control compara las tasas de conversión por variante, incluyendo la significancia estadística (una prueba z).

Instalación

@intlayer/analytics es una dependencia par y opcional — nunca instalada automáticamente por un paquete de framework. Añádela junto a intlayer:

npm install @intlayer/analytics

Si no lo instalas, todos los puntos de integración se resuelven como una operación nula (no-op) — consulta Costo cero cuando no está instalado a continuación.

Configuración

Analytics reutiliza el bloque de configuración editor existente — no hay un esquema de configuración analytics separado que rellenar:

import type { IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  editor: {
    backendURL: "https://back.intlayer.org", // También usado como endpoint de ingesta de analíticas
    clientId: "your-client-id", // También usado como clave de proyecto de analíticas
    clientSecret: "your-client-secret",
  },
};

export default config;

• editor.backendURL — la URL base a la que se envían los eventos de analíticas (POST {backendURL}/api/analytics/events).
• editor.clientId — la clave pública del proyecto atribuida a cada evento ingerido. También actúa como el interruptor de encendido: las analíticas permanecen totalmente desactivadas (y eliminadas del código final) hasta que se configura el clientId.

Si autoalojas Intlayer, las analíticas apuntan automáticamente a tu propia instancia, ya que comparte editor.backendURL.

Soporte de frameworks

Analytics está integrado en el IntlayerProvider compartido de react-intlayer, por lo que está disponible hoy en cualquier lugar donde se use ese proveedor:

Uso

Seguimiento automático a nivel de proveedor

No se requieren cambios en el código. Una vez que @intlayer/analytics está instalado y editor.clientId está configurado, IntlayerProvider automáticamente:

• inicializa el cliente de analíticas al montarse,
• registra un page_view en la carga inicial,
• registra un page_view en cada cambio de locale,
• inicia el ciclo de vaciado (flush) de ~20s y envía cualquier evento restante al desmontar / cerrar pestaña (vía navigator.sendBeacon, con respaldo a fetch(..., { keepalive: true })).

Seguimiento automático a nivel de nodo

Cada vez que useIntlayer resuelve un fragmento de contenido para mostrar, el intérprete reporta un evento de content_exposure para esa exacta dictionaryKey + ruta de clave + locale — de nuevo, no se requieren cambios en el código. Las exposiciones repetidas del mismo nodo dentro de una ventana de vaciado se fusionan en un solo evento con un contador (count), por lo que una lista que se vuelve a renderizar 50 veces no envía 50 eventos.

Seguimiento de conversiones para pruebas A/B

Usa useConversion() para atribuir un objetivo a la variante que vio una sesión:

Resolución de una variante en el lado del cliente

Privacidad y rendimiento

• Anónimo por diseño: las sesiones se identifican mediante una ID rotatoria; el backend solo almacena un hash SHA-256 de esa ID — nunca la ID en crudo, nunca una dirección IP.
• La ubicación es aproximada: solo un código de país, derivado de las cabeceras de geolocalización del CDN (cf-ipcountry, x-vercel-ip-country, ...) — no se lee ni almacena ninguna IP.
• Las URLs excluyen los parámetros de búsqueda por defecto, por lo que las cadenas de consulta nunca se capturan.
• Muestreo: sampleRate te permite conservar solo una fracción de los eventos de exposición de contenido en aplicaciones con mucho tráfico.
• Por lotes: una solicitud aproximadamente cada 20 segundos (flushInterval), o antes si el búfer se llena (maxBufferSize) — nunca una solicitud por evento.

Costo cero cuando no está instalado

@intlayer/analytics sigue exactamente el mismo patrón de dependencia opcional que @intlayer/editor:

• cada punto de integración carga el paquete a través de un import() dinámico envuelto en try/catch — una app que nunca instala @intlayer/analytics nunca paga un costo de tamaño de bundle o tiempo de ejecución, y nunca ve un error;
• una variable de entorno en tiempo de compilación (INTLAYER_ANALYTICS_ENABLED), configurada automáticamente en 'false' por @intlayer/config cuando editor.clientId no está configurado, permite a los empaquetadores eliminar el código muerto de toda la integración;
• las analíticas se desactivan dentro del iframe de vista previa del editor/CMS de Intlayer, por lo que las sesiones de edición nunca se cuentan como tráfico real.

Panel de control: Página de Analíticas

Una vez que tu proyecto haya recopilado eventos, la página de Analytics en el panel de control de Intlayer (visible en la barra lateral una vez que se selecciona un proyecto) muestra:

• Usuarios activos — visitantes únicos durante el período móvil seleccionado (7 / 30 / 90 días).
• Usuarios hoy y usuarios en los últimos 7 días.
• Vistas de página durante el período seleccionado.
• Un gráfico de evolución de visitantes únicos diarios.
• Pestañas de desglose de Configuraciones regionales (Locales) y Ubicación, clasificando tu audiencia por locale y por país.

Referencia de la API del Backend

Todos los endpoints de lectura requieren autenticación; la ingesta es pública y se atribuye por el clientId.

También puedes llamar a estos programáticamente con el SDK del CMS:

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

Enlaces útiles

• Diccionarios Dinámicos - Colecciones y Variantes
• CMS de Intlayer - SDK del CMS
• Editor Visual de Intlayer
• Referencia de Configuración
• Guía de Autoalojamiento