citlyze docs
Usar Citlyze

Instalar el seguimiento de rastreadores de IA

Guías de instalación paso a paso para Cloudflare, Vercel, WordPress, servidores Node propios, Webflow y Shopify.

Esta página explica, paso a paso, cada forma de instalación. Para saber qué mide el seguimiento de rastreadores y cómo funciona la verificación, consulta Rastreadores de IA. La misma instalación también registra las visitas humanas que llegan desde respuestas de IA, así que al completarla alimentas también Tráfico de IA; las opciones que solo usan el navegador para esa página se explican en Instalar el seguimiento de tráfico de IA.

Elige la guía según dónde funcione tu sitio:

Tu configuraciónGuía que debes seguir
El sitio está detrás de Cloudflare (proxy con la nube naranja)Worker de Cloudflare
App de Next.js en Vercel (o Next.js en tus propios servidores)Middleware de Vercel / Next.js
Sitio de WordPressPlugin de WordPress
Sitio hecho a medida en tus propios servidores (AWS, GCP, Azure, VPS, contenedores)Servidor propio / Node
Sitio de WebflowWebflow
Tienda de ShopifyShopify

Antes de empezar: genera una clave de sitio

Todas las instalaciones necesitan una clave de sitio, uses la plataforma que uses:

  1. En la app, ve a Ajustes → Conexiones → Seguimiento del sitio web.
  2. Haz clic en Generar clave de sitio. Ponle un nombre a la clave y, si puedes, el dominio desde el que enviará datos; el dominio también refuerza la verificación de los rastreadores firmados en ese sitio.
  3. Copia los dos valores del cuadro de confirmación: el ID de clave y el secreto de firma (empieza por ctk_). El secreto se muestra una sola vez; si lo pierdes, usa Rotar en la clave para generar uno nuevo.

No compartas el secreto de firma: cualquiera que lo tenga puede enviar datos de tráfico falsos en nombre de tu sitio. Los fragmentos para Cloudflare, Vercel y servidor propio lo leen de una variable de entorno llamada CITLYZE_SIGNING_SECRET, así que nunca aparece en tu código; el plugin de WordPress lo guarda en sus ajustes. No lo subas nunca a un repositorio ni lo pegues en código que se ejecute en el navegador.

Worker de Cloudflare

Úsalo si tu DNS está en Cloudflare y el sitio pasa por su proxy (el interruptor de la nube naranja). Es la opción más completa: ve todas las peticiones en el perímetro de la red, envía los códigos de estado HTTP reales y funciona sea cual sea la tecnología que haya detrás de Cloudflare.

  1. En Ajustes → Conexiones → Seguimiento del sitio web → Instalar fragmento, abre la pestaña Cloudflare y copia el fragmento.
  2. Sustituye SITE_KEY_ID en el fragmento por tu ID de clave. El secreto de firma no va en el código; lo añadirás como secreto del Worker en el paso 5.
  3. En el panel de Cloudflare, ve a Workers & Pages → Create → Create Worker. Ponle un nombre (por ejemplo, ai-crawler-tracker) y haz clic en Deploy para crear el worker vacío.
  4. Haz clic en Edit code, sustituye el ejemplo generado por tu fragmento y vuelve a hacer clic en Deploy.
  5. Añade el secreto de firma: en el worker, abre Settings → Variables and Secrets → Add, elige el tipo Secret, ponle el nombre CITLYZE_SIGNING_SECRET, pega tu secreto de firma y haz clic en Deploy. Cloudflare lo guarda cifrado y nunca aparece en el código del worker.
  6. Conecta el worker a tu sitio: en el worker, abre Settings → Domains & Routes → Add → Route, elige tu zona y añade la ruta example.com/*. Si tu sitio también se sirve en www.example.com, añade una segunda ruta para www.example.com/*.
  7. Listo: no hay que cambiar nada en el código de tu sitio. El worker pasa todas las peticiones a tu origen sin modificarlas y, en segundo plano, informa de las visitas que cumplen los criterios.

Comprueba dos cosas:

  • La ruta debe cubrir todas las rutas (/*); si no, las visitas de rastreadores a las páginas que quedan fuera no se ven.
  • Si ya tienes un worker en esas rutas: Cloudflare solo ejecuta un worker por ruta, así que integra la lógica del fragmento en tu worker actual en lugar de añadir otro.

Middleware de Vercel / Next.js

Úsalo con una app de Next.js desplegada en Vercel. El mismo archivo también funciona si alojas Next.js en tus propios servidores.

  1. En Ajustes → Conexiones → Seguimiento del sitio web → Instalar fragmento, abre la pestaña Vercel / Proxy y copia el fragmento.
  2. En tu repositorio de Next.js, crea middleware.ts en la raíz del proyecto (o en src/ si tu app está ahí) y pega el fragmento.
  3. Sustituye SITE_KEY_ID por tu ID de clave. El secreto de firma no va en el archivo.
  4. En tu proyecto de Vercel, abre Settings → Environment Variables y añade CITLYZE_SIGNING_SECRET con tu secreto de firma en cada entorno que quieras medir. Márcala como Sensitive. ¿Alojas Next.js en tus propios servidores? Define la misma variable en el entorno de tu servidor.
  5. Si ya tienes un middleware.ts, no añadas otro archivo: Next.js solo ejecuta uno. Copia el bloque de funciones auxiliares del fragmento en tu archivo actual, llama a su lógica de envío al principio de tu función de middleware y comprueba que la configuración de matcher sigue cubriendo todas las rutas.
  6. Haz commit y despliega.

Notas:

  • El middleware se ejecuta antes de que exista la respuesta, así que los eventos indican su estado HTTP como unknown. Es normal. Para tener códigos de estado, usa el log drain de Vercel en lugar de este middleware (si usas los dos, cada visita se cuenta dos veces), o usa la instalación de Cloudflare o de servidor propio, que también envían las redirecciones.
  • En Vercel, la IP del visitante se toma de una cabecera que añade la propia plataforma, así que es fiable. Si alojas Next.js en tus propios servidores detrás de tu propio proxy, asegúrate de que la cabecera de IP reenviada que lee el fragmento la añade tu proxy y no llega tal cual desde el cliente.

Plugin de WordPress

Úsalo en cualquier sitio de WordPress en el que puedas instalar plugins.

El mismo plugin también comprueba gratis qué rastreadores de IA deja pasar tu robots.txt y qué bloquea al resto; consulta Plugin de WordPress.

  1. En el panel de administración de WordPress, ve a Plugins → Añadir nuevo, busca AI Crawler Control by Citlyze y haz clic en Instalar ahora y después en Activar. El plugin está en el directorio oficial de WordPress.org, así que no hace falta subir ningún zip.

  2. ¿Prefieres instalarlo a mano? En Ajustes → Conexiones → Seguimiento del sitio web → Instalar fragmento, abre la pestaña WordPress, haz clic en Descargar plugin y sube el zip en Plugins → Añadir nuevo → Subir plugin.

  3. Ve a Citlyze → Connect Citlyze y rellena los tres campos:

    • Tracker base URL: https://app.citlyze.com
    • Key ID: tu ID de clave
    • Signing secret: tu secreto ctk_... El plugin no envía nada hasta que rellenes la URL base.
  4. Haz clic en Send test event. Deberías ver una confirmación de conexión; así compruebas de principio a fin tus credenciales y la conexión.

  5. ¿Tu sitio está detrás de un proxy o de un balanceador de carga que no sea Cloudflare? En Visitor IP behind a proxy, elige la cabecera que añade tu proxy e indica sus direcciones, para que los rastreadores se puedan verificar por su IP real. Si usas Cloudflare, no hace falta nada.

El plugin envía los datos después de servir cada página, con el código de estado exacto, incluidas las peticiones que otro plugin redirige antes de renderizar la página. Los eventos esperan en tu base de datos de WordPress y se envían por lotes; la pantalla Connect Citlyze muestra cuántos hay pendientes y cuándo se entregaron por última vez.

Ten en cuenta que las páginas servidas desde una caché de página completa, las redirecciones que hace tu servidor web o tu CDN y las peticiones que un firewall bloquea antes de que se cargue WordPress nunca llegan al plugin. La pantalla Connect Citlyze te avisa si detecta una caché de página. Si tu sitio usa mucha caché, es preferible instalar el Worker de Cloudflare o subir los registros de tu servidor.

Servidor propio / Node

Úsalo en sitios hechos a medida que alojas tú mismo: AWS, Google Cloud, Azure, un VPS o contenedores. El fragmento es un middleware de estilo Express para Node 20 o posterior (también funciona en Bun y Deno).

  1. En Ajustes → Conexiones → Seguimiento del sitio web → Instalar fragmento, abre la pestaña Servidor propio / Node y copia el fragmento.
  2. Guárdalo como aeo-tracker.mjs junto al punto de entrada de tu servidor.
  3. Sustituye SITE_KEY_ID por tu ID de clave y define en el servidor la variable de entorno CITLYZE_SIGNING_SECRET con tu secreto de firma: en la configuración de secretos de tu proveedor o en un archivo .env que nunca se suba al repositorio. El secreto nunca va en el propio archivo.
  4. Registra el middleware antes de tus rutas:
    import { aeoCrawlerTracker } from "./aeo-tracker.mjs";
    app.use(aeoCrawlerTracker());
  5. Si tu servidor está detrás de un balanceador de carga o de un proxy inverso (nginx, ALB), configura Express para que confíe en él (por ejemplo, app.set("trust proxy", 1)), para que el middleware envíe la IP real del cliente y no la del proxy. Es la IP que se comprueba al verificar la identidad de los rastreadores.
  6. Despliega. El middleware envía los datos cuando termina cada respuesta, así que no añade latencia e incluye los códigos de estado HTTP reales.

¿No usas Express? La función que devuelve recibe los argumentos habituales (req, res, next) y se adapta a Fastify, Koa o al servidor http de Node. Para otros lenguajes (Python, Go, PHP, Ruby, etc.), implementa el protocolo de baliza firmada; cada POST HTTPS firmado lleva un lote de hasta 50 peticiones que cumplen los criterios.

Webflow

El alojamiento de Webflow no permite ejecutar código en el servidor, y los scripts del navegador no detectan a los rastreadores de entrenamiento de IA, así que el seguimiento se instala en una capa de proxy delante de Webflow:

  1. Webflow admite proxies inversos gestionados por el cliente en los planes Enterprise; organízalo con tu contacto de Webflow y haz que tu dominio pase por tu proxy (Cloudflare, CloudFront, Fastly o tu propio nginx).
  2. Instala el seguimiento en esa capa de proxy:
  3. Comprueba la instalación como se explica más abajo.

Las apps de Webflow Cloud no sirven para hacer el seguimiento de todo el sitio: solo atienden las peticiones que llegan a su ruta de montaje, así que nunca ven las visitas de rastreadores a tus páginas normales.

Shopify

Las tiendas Shopify estándar no pueden usar este seguimiento: Shopify no permite a los comerciantes ejecutar código en el servidor con las peticiones a la tienda ni admite poner un proxy (como Cloudflare) delante de una tienda. Los scripts del navegador no son una alternativa: los rastreadores de entrenamiento de IA nunca ejecutan JavaScript, y un script en el navegador dejaría a la vista tu secreto de firma.

Qué puedes hacer:

  • Las tiendas headless creadas con Hydrogen y alojadas en Oxygen (o en cualquier infraestructura propia) ejecutan código en el servidor; integra la lógica del fragmento de Servidor propio / Node en el gestor de peticiones del servidor de tu tienda.
  • En las tiendas estándar, el resto de mediciones de Citlyze (seguimiento de prompts, citas, auditorías GEO) funciona igual, esté donde esté alojada la tienda.

Verifica tu instalación

  • En Ajustes → Conexiones → Seguimiento del sitio web, la tabla de claves de sitio tiene una columna Último evento. Se actualiza en cuanto tu instalación entrega su primer envío aceptado; cuentan tanto las visitas de rastreadores como los clics desde respuestas de IA.
  • Si usas WordPress, puedes confirmar la entrega al momento con Send test event (los eventos de prueba comprueban las credenciales y la conexión, pero no actualizan Último evento).
  • Ten paciencia: en sitios con poco tráfico, la primera visita real de un rastreador puede tardar horas o unos días. En cuanto llegan eventos, Diagnosticar → Actividad de rastreadores de IA → Resumen empieza a mostrar datos.
  • Si no llega nada después de un par de días, comprueba que el ID de clave de tu fragmento (o de los ajustes del plugin) corresponde a una clave activa y no revocada, que CITLYZE_SIGNING_SECRET contiene el secreto de firma actual de esa clave y que tu ruta o tu middleware cubre todas las rutas. Sin un secreto válido, el fragmento no envía nada y registra una sola vez «Citlyze crawler tracking is off».
  • La tabla de claves de sitio también muestra qué versión del colector envía datos con cada clave, y te avisa cuando hay una versión más reciente del fragmento o del plugin, o cuando el plugin de WordPress ha detectado una caché de página.

En esta página