# AI Referrer Detection Middleware

Detect when a visitor arrives from an AI search assistant (ChatGPT,
Perplexity, Claude, Gemini, Copilot, etc.) and tag the session for
analytics, contextual UX, and GEO/AEO citation tracking.

**MIT License · Production-tested at coreindustry.de · ~50 LOC.**

---

## Why this exists

Google Analytics and most analytics tools group AI traffic as "Direct"
or "Other" because (a) the `referer` header gets stripped, (b) the
hostnames vary between products, (c) there's no `utm_source` injection
from the AI tools themselves.

For sites running GEO/AEO experiments — measuring whether your content
gets cited by LLMs — knowing which AI sent the click is essential.

## What it does

1. Reads `Referer` header on every middleware-routed request
2. Matches against a curated list of 12 AI assistant origins:
   - `chat.openai.com`, `chatgpt.com` → `chatgpt`
   - `perplexity.ai`, `*.perplexity.ai` → `perplexity`
   - `claude.ai` → `claude`
   - `gemini.google.com`, `aistudio.google.com` → `gemini`
   - `copilot.microsoft.com`, `bing.com/copilot` → `copilot`
   - `you.com` → `you`
   - `phind.com` → `phind`
   - `kagi.com` → `kagi`
3. Sets `__ai_src` cookie (SameSite=Lax, 7 days, client-readable so
   client components can render contextual UI)
4. Sets `x-ai-source` response header for server-side log/analytics
   pipelines
5. Only sets the cookie on FIRST inbound — preserves original source
   across the session

## Latency impact

~30 µs per request. Pure regex matching, no async I/O.

## Usage

Drop the file into your Next.js 15+ project. Import + call in your
existing `middleware.ts`:

```ts
import { detectAiSource, attachAiSourceCookie } from './lib/ai-referrer'

export function middleware(req: NextRequest) {
  const res = NextResponse.next()
  const aiSource = detectAiSource(req)
  if (aiSource && !req.cookies.get('__ai_src')) {
    attachAiSourceCookie(res, aiSource)
  }
  return res
}
```

## Companion: AI-Inbound Banner Component

For sites that want to render a contextual welcome banner when an AI
visitor arrives, see [`AiInboundBanner.tsx`](./AiInboundBanner.tsx).
The banner:
- Reads the `__ai_src` cookie client-side
- Shows a small floating welcome ("Welcome from Claude")
- Surfaces 3 top FAQ questions
- Single CTA (no clutter)
- Dismissable for 7 days

We measured a 22 % lower bounce rate on AI-inbound sessions when this
banner replaces the default homepage hero for those visitors.

## What it does NOT do

- **No fingerprinting** — only matches the public `referer` header
- **No PII storage** — cookie value is just a short slug like `claude`
- **No external API calls** — fully self-contained at the edge

## DSGVO note

The `__ai_src` cookie is a strictly necessary functional cookie
(referer-mirror, no tracking ID). Under DSGVO Art. 6(1)(f) legitimate
interest applies — no banner consent required IF you only use it for
contextual UX. If you also pipe it into analytics (Clarity, GA), use
your existing analytics-consent banner.

## Built by

[Core Industry](https://coreindustry.de) — we use this on our own site
to measure which LLMs cite us most. After 30 days of data, Perplexity
was ~3 × Claude inbound, and ChatGPT-routed clicks converted 2.4 × the
rate of organic Google.

## License

MIT — no attribution required, but if you publish a blog post about
LLM-traffic measurement, a link to coreindustry.de's AI-Inbound case
study would be appreciated.