WorkOfNeo/analyticsos-skills

Seguimiento con analyticsOS

analyticsOS registra vistas de página, clics, desplazamientos, formularios, errores, velocidad y usuarios autenticados a través de un único script por aplicación. Instalarlo son dos etiquetas en el <head> de la página; la mayor parte del trabajo consiste en colocarlas en el lugar correcto para la pila tecnológica y mantener los datos personales fuera.

Lo que necesitas de la persona

La página de configuración de analyticsOS le proporciona un aviso con tres valores. Pregunta por cualquiera que falte; nunca los adivines.

• Host: dónde se ejecuta su analyticsOS, ej. https://analytics.example.com.
• Key: la clave pública de la aplicación, prj_…. No es un secreto: termina en cada página que carga el script.
• Modo: Identified (aplicaciones con inicio de sesión, consentimiento en su acuerdo) o Anonymous (sitios públicos, nada almacenado en el dispositivo).

Instalar

1. Encuentra la pila y lee su referencia antes de cambiar nada:

   • Next.js (App Router o Pages Router): references/nextjs.md
   • Flask u otra aplicación Jinja: references/flask.md
   • Webflow: references/webflow.md
   • Cualquier otra cosa (HTML plano, Vite, Astro, SvelteKit, Rails, Django, PHP, WordPress…): references/any-site.md

2. Variables de entorno, no valores fijos: ANALYTICS_HOST y ANALYTICS_KEY, con el prefijo que la compilación necesite para exponerlas a la página (NEXT_PUBLIC_ para Next.js, VITE_ para Vite). Ponlas en el archivo .env local, añade los nombres con valores vacíos a .env.example e indica a la persona que las configure en los ajustes de su alojamiento (Railway → Variables, Vercel → Variables de Entorno…) para cada entorno donde deba ejecutarse el seguimiento.

3. Las dos etiquetas, en <head> en cada página, solo cuando la clave está establecida. Sin clave no debe cargar nada: ese es el interruptor de apagado para el desarrollo local y las vistas previas.

   <script>
     window.aos =
       window.aos ||
       function () {
         ;(window.aos.q = window.aos.q || []).push(arguments)
       }
   </script>
   <script defer src="{ANALYTICS_HOST}/s/{ANALYTICS_KEY}.js"></script>
   

   La primera etiqueta pone en cola las llamadas realizadas antes de que cargue el script; la segunda carga el script con la configuración de la aplicación.

4. Usuarios autenticados (solo modo Identified): consulta references/events.md. En modo Anonymous no añadas llamadas de identificación y no almacenes nada sobre el visitante.

5. Nombra las secciones principales de las páginas clave con data-section="Precios" (hero, precios, formulario de registro…) para que los informes puedan nombrarlas, y pon data-private en cualquier elemento cuyo texto nunca deba leerse: nombres de clientes, cantidades, direcciones, cualquier dato personal.

6. Content-Security-Policy: si el proyecto establece una, permite el host en script-src y connect-src.

7. Nada más: no añadas otras analíticas, cookies ni banners de consentimiento. analyticsOS no necesita ninguno de ellos.

8. Finalizar: ejecuta la compilación y el linter del proyecto, enumera los archivos que cambiaste e indica a la persona que abra la aplicación en un navegador. La página de configuración en analyticsOS marca la primera vista de página en segundos.

Lo que el script ya captura

No escribas código para ninguna de estas; vienen con el script:

• vistas de página, incluyendo navegaciones del lado del cliente en aplicaciones de una sola página;
• clics en enlaces, botones y cualquier cosa con data-aos-event, además de enlaces externos, descargas, clics de ira y clics muertos;
• profundidad de desplazamiento y tiempo en la página;
• formularios iniciados, enviados y abandonados (nunca lo que se escribió);
• Core Web Vitals (LCP, INP, CLS, FCP, TTFB), errores de JavaScript y solicitudes fallidas del mismo origen.

Los eventos personalizados, clics nombrados e identificación están en references/events.md.

Reglas de privacidad

Estas se mantienen en todos los proyectos, sea lo que sea que pida la persona:

• Nunca envíes una dirección de correo electrónico, nombre, número de teléfono ni nada que una persona haya escrito: no en rasgos de identify, no en propiedades de track, no en nombres de data-aos-event.
• Identifica con el ID de usuario interno de la aplicación, nunca con el correo electrónico.
• Marca los elementos que muestren datos personales con data-private. El script tampoco lee nunca inputs, textareas ni contenteditable.
• Los navegadores que envían Do Not Track o Global Privacy Control no son rastreados en absoluto, y las llamadas aos() se descartan. No intentes evitarlo.

Cuando no llega nada

Abre la aplicación con la pestaña de red del navegador:

• /s/{key}.js debería cargarse (200), luego las solicitudes a {host}/api/e responden con 204.
• 403 de /api/e: el dominio de la página no está en los dominios permitidos de la aplicación (analyticsOS → ajustes de la aplicación). Añádelo, o deja la lista vacía durante las pruebas.
• 404: la clave es incorrecta o fue rotada hace más de 24 horas.
• Sin solicitudes en absoluto: la variable de clave no está configurada en ese entorno, una Content-Security-Policy bloquea el host, o el navegador envía Do Not Track / Global Privacy Control.
• Next.js, los eventos se detienen después de la primera página: las etiquetas se añadieron como elementos <script> simples en un diseño anidado. Usa next/script en el diseño raíz (consulta references/nextjs.md).