@orionai/tracker

Official Orion bot tracking middleware for Next.js, Nuxt.js, and Node.js applications.

Track AI crawler bots (GPTBot, ClaudeBot, PerplexityBot, etc.) server-side with 100% accuracy.

Why Server-Side Tracking?

AI bots like GPTBot and ClaudeBot don't execute JavaScript, so traditional analytics snippets miss 70-90% of bot visits. This middleware tracks bots at the server level before any JavaScript runs.

Installation

npm install @orionai/tracker

Quick Start

Next.js (App Router)

Create or update middleware.ts in your project root:

import { NextResponse, type NextRequest } from 'next/server'
import { orionBotTracker } from '@orionai/tracker'

export async function middleware(request: NextRequest) {
  const response = NextResponse.next()
  
  await orionBotTracker(request, response, {
    trackingKey: 'your_orion_tracking_key_here',
    apiUrl: 'https://orion-backend-d7rs.onrender.com', // Optional
    debug: false, // Set to true for development
  })
  
  return response
}

export const config = {
  matcher: [
    '/((?!_next/static|_next/image|favicon.ico|.*\\.(?:svg|png|jpg|jpeg|gif|webp)$).*)',
  ],
}

Next.js (Pages Router)

Create pages/_middleware.ts:

import { NextResponse, type NextRequest } from 'next/server'
import { orionBotTracker } from '@orionai/tracker'

export async function middleware(request: NextRequest) {
  const response = NextResponse.next()
  
  await orionBotTracker(request, response, {
    trackingKey: 'your_orion_tracking_key_here',
  })
  
  return response
}

Nuxt.js 3

Create server/middleware/orion.ts:

import { orionBotTracker } from '@orionai/tracker'

export default defineEventHandler(async (event) => {
  await orionBotTracker(event.node.req, event.node.res, {
    trackingKey: 'your_orion_tracking_key_here',
  })
})

Cloudflare Workers

import { orionBotTracker } from '@orionai/tracker'

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const response = new Response('Hello World')
    
    await orionBotTracker(request, response, {
      trackingKey: env.ORION_TRACKING_KEY,
    })
    
    return response
  },
}

Express.js

import express from 'express'
import { orionBotTracker } from '@orionai/tracker'

const app = express()

app.use(async (req, res, next) => {
  await orionBotTracker(req, res, {
    trackingKey: process.env.ORION_TRACKING_KEY!,
  })
  next()
})

Configuration

| Option | Type | Required | Default | Description | |--------|------|----------|---------|-------------| | trackingKey | string | ✅ Yes | - | Your Orion tracking key (find in dashboard) | | apiUrl | string | No | Orion API | Custom API endpoint (for self-hosted) | | debug | boolean | No | false | Enable console logging for debugging | | timeout | number | No | 5000 | Request timeout in milliseconds |

Getting Your Tracking Key

1. Log in to your Orion dashboard
2. Go to Settings → Tracking Keys
3. Copy your tracking key (starts with ork_)

What Bots Are Tracked?

AI Crawlers

• ✅ GPTBot (OpenAI)
• ✅ ChatGPT-User (OpenAI)
• ✅ ClaudeBot (Anthropic)
• ✅ Claude-Web (Anthropic)
• ✅ PerplexityBot (Perplexity)
• ✅ Google-Extended (Google Gemini)
• ✅ Cohere-Bot (Cohere)

Search Engine Crawlers

• ✅ Googlebot
• ✅ Bingbot
• ✅ Applebot
• ✅ YandexBot
• ✅ DuckDuckBot

Social Media Bots

• ✅ FacebookBot
• ✅ TwitterBot
• ✅ LinkedInBot
• ✅ SlackBot
• ✅ DiscordBot

Total: 20+ bot types tracked

Verification

After installation, visit your site with a bot user agent to test:

# Test GPTBot detection
curl -A "Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko) ChatGPT-User/1.0" https://yoursite.com

# Check Orion dashboard
# You should see the bot visit appear within 1-2 minutes

Or use the built-in verification in your Orion dashboard:

• Go to Monitoring → Bot Activity
• Click "Test Installation"

Troubleshooting

Not seeing bot visits?

1. Check your tracking key is correct (starts with ork_)
2. Verify middleware is running:

   orionBotTracker(request, response, {
     trackingKey: 'your_key',
     debug: true, // Enable logging
   })

3. Check the matcher config (Next.js) - make sure it includes your routes
4. Verify deployment - middleware only runs in production/preview, not localhost

Bot visits not appearing in real-time?

• Bot tracking data is processed asynchronously
• Allow 1-2 minutes for data to appear in your dashboard

Getting rate limited?

• Default timeout is 5 seconds
• Tracking is fire-and-forget (won't block your site)
• If issues persist, contact [email protected]

Performance Impact

• Latency: < 5ms (fire-and-forget request)
• Blocking: No - tracking happens asynchronously
• Bandwidth: < 1 KB per bot visit

Support

• 📧 Email: [email protected]
• 📚 Docs: https://useorion.ai/docs
• 💬 Discord: https://discord.gg/orion (coming soon)

License

MIT © Orion AI

Made with ❤️ by the Orion team