DOCS // BOT TRACKING

Monitoreá crawlers IA en tu app Next.js

Registrá cada vez que un bot de IA conocido rastrea tu sitio. Middleware liviano, cero dependencias extra, 5 minutos de setup. Gratis para todos los clientes de CLICON.

¿Qué es el bot tracking?

Los crawlers de Anthropic, OpenAI, Perplexity, Google y otros ya escanean la web regularmente. Saber cuándo y qué rastrean en tu sitio es infraestructura crítica para la era agéntica.

El middleware de CLICON detecta 9 bots de IA conocidos por User-Agent y reporta cada hit a tu dashboard de Lotus en tiempo real. Sin impacto en performance, sin JavaScript del lado del cliente, sin dependencias extra.

9 bots detectados

El middleware compara los headers User-Agent contra estos crawlers de IA usando patrones regex case-insensitive:

PerplexityBot
Crawler de Perplexity AI
GPTBot
Crawler GPTBot de OpenAI
Claude-Bot
ClaudeBot de Anthropic (detecta Claude-Bot y ClaudeBot)
Google-Extended
Google Extended (crawler de opt-out de entrenamiento de Gemini)
Bingbot
Crawler de Microsoft Bing
Applebot-Extended
Applebot Extended (crawler de Apple Intelligence)
Meta-ExternalAgent
Meta External Agent (crawler de entrenamiento de Llama)
Bytespider
Crawler Bytespider de ByteDance
CCBot
Common Crawl bot

Instalación

Tres pasos. Cinco minutos. Cero dependencias nuevas.

PASO 1

Configurá LOTUS_TRACKING_KEY en Vercel

Agregá la variable de entorno LOTUS_TRACKING_KEY a tu proyecto en Vercel. Podés encontrar tu key en el panel de administración de Lotus, en Settings → API Keys. El middleware usa esta key para autenticar las requests de tracking a la API de Lotus.

PASO 2

Agregá el middleware a tu proyecto Next.js

Copiá este archivo como middleware.ts en la raíz de tu proyecto Next.js. Este único archivo maneja tanto la detección de bots como el ruteo i18n. Si ya tenés un middleware, mergeá el bloque de detección de bots en el tuyo — se ejecuta antes que tu lógica existente.

middleware.tstypescript
import createMiddleware from "next-intl/middleware";
import { NextRequest } from "next/server";
import { routing } from "./i18n/routing";

const intlMiddleware = createMiddleware(routing);

const KNOWN_BOTS: Array<{ pattern: RegExp; canonical: string }> = [
  { pattern: /PerplexityBot/i,      canonical: "PerplexityBot" },
  { pattern: /GPTBot/i,             canonical: "GPTBot" },
  { pattern: /Claude-?Bot/i,        canonical: "Claude-Bot" },
  { pattern: /Google-Extended/i,    canonical: "Google-Extended" },
  { pattern: /bingbot/i,            canonical: "Bingbot" },
  { pattern: /Applebot-Extended/i,  canonical: "Applebot-Extended" },
  { pattern: /meta-externalagent/i, canonical: "Meta-ExternalAgent" },
  { pattern: /Bytespider/i,         canonical: "Bytespider" },
  { pattern: /CCBot/i,              canonical: "CCBot" },
];

function detectBot(userAgent: string): string | null {
  for (const { pattern, canonical } of KNOWN_BOTS) {
    if (pattern.test(userAgent)) return canonical;
  }
  return null;
}

export default async function middleware(req: NextRequest) {
  const userAgent = req.headers.get("user-agent") || "";
  const bot = detectBot(userAgent);

  if (bot) {
    const trackingKey = process.env.LOTUS_TRACKING_KEY;
    if (trackingKey) {
      const url = new URL(req.url);
      const clientDomain = url.hostname.replace(/^www\./, "");
      try {
        await fetch("https://lotus.clicon.app/api/v1/track/bot-hit", {
          method: "POST",
          headers: {
            "Content-Type": "application/json",
            "X-API-Key": trackingKey,
          },
          body: JSON.stringify({
            client_domain: clientDomain,
            bot_name: bot,
            endpoint_accessed: url.pathname,
          }),
        });
      } catch (err) {
        console.error("[bot-tracking] POST failed:", err);
      }
    }
  }

  return intlMiddleware(req);
}

export const config = {
  matcher: [
    "/((?!api|_next|_vercel|outstatic|.*\\..*).*)",
  ],
};
PASO 3

Agregá LOTUS_TRACKING_KEY a env.d.ts (solo TypeScript)

Si usás TypeScript, declaralo en tu archivo env.d.ts o next-env.d.ts para que Next.js lo reconozca. Este paso es opcional pero recomendado para type safety.

Verificá que funcione

Deployá tu app y ejecutá este comando curl desde tu terminal. Simula un request de PerplexityBot a tu dominio en producción:

curlbash
curl -A "Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; PerplexityBot/1.0; +https://perplexity.ai/perplexitybot)" \\
  -o /dev/null -w "%{http_code}\\n" https://tu-dominio.com/

Deberías ver una respuesta 200. Revisá tu dashboard de Lotus — el hit va a aparecer en Bot Traffic en segundos. Si ves otro status code, revisá la sección de troubleshooting más abajo.

Problemas comunes

El middleware no se ejecuta

Verificá que middleware.ts esté en la raíz de tu proyecto Next.js (mismo nivel que next.config). También chequeá que el matcher config no esté excluyendo la ruta que estás probando.

LOTUS_TRACKING_KEY es undefined

Confirmá que la variable de entorno esté seteada en Vercel (Settings → Environment Variables) y redeployada. Para desarrollo local, agregala a .env.local — nunca commitees este archivo.

Los hits no aparecen en el dashboard

El POST de tracking se ejecuta async y sus errores se capturan en silencio para no romper tu app. Revisá los logs de funciones de Vercel buscando entradas [bot-tracking]. También verificá tu API key en el panel de Lotus.

Recibo 401 del endpoint de tracking

Tu LOTUS_TRACKING_KEY es inválida o expiró. Generá una nueva key desde el panel de administración de Lotus y actualizá la variable de entorno en Vercel.

¿Necesitás ayuda?

Si tenés problemas o necesitás una tracking key, escribinos a martin@clicon.app.

← Volver al inicio