AI Growth Bot Analytics

Zero-code bot tracking for Node.js servers. Automatically detects and tracks bot traffic (Googlebot, ChatGPT, Claude, etc.) and sends events to your analytics dashboard.

Installation

npm install @ai-growth/bot-analytics

That's it! No code changes needed.

Setup

1. Create a .env file in your project root with your API token:

AIGROWTH_API_TOKEN=your_api_token_here
AIGROWTH_ACCOUNT_ID=optional_account_id

2. The package automatically injects itself into your npm scripts (start, dev, serve, start:prod, preview).

3. Start your application normally. The package will automatically begin tracking bot traffic.

Supported Frameworks

• Express.js
• Fastify
• NestJS
• Next.js
• Pure Node.js HTTP servers

How It Works

The package uses Node.js's NODE_OPTIONS environment variable to pre-load a module that intercepts HTTP requests at the Node.js core level. This means:

• No code changes required in your application
• Works with any HTTP framework
• Zero runtime overhead for non-bot requests
• Automatically detects over 25+ bot types

Detected Bots

• Search engines: Googlebot, Bingbot, DuckDuckBot, BaiduSpider, Yandexbot, Slurp
• Social media: FacebookBot, TwitterBot, LinkedInBot, PinterestBot
• AI models: GPTBot, ChatGPT-User, ClaudeBot, PerplexityBot, AnthropicAI, CCBot
• Messaging: WhatsAppBot, TelegramBot
• Others: AppleBot, SpotifyBot, MSNBot, AhrefsBot, SemrushBot, and more

Data Collected

For each bot request, the following is sent to analytics.aigrowthagent.co/bot-track:

{
  "bot_name": "Googlebot",
  "bot_category": "Search Engines",
  "host": "example.com",
  "ip": "203.0.113.42",
  "page_url": "/robots.txt",
  "account_id": "optional"
}

HTTP Headers:

• X-API-Key: {AIGROWTH_API_TOKEN}
• Content-Type: application/json

Environment Variables

• AIGROWTH_API_TOKEN (required) - Your API token for analytics
• AIGROWTH_ACCOUNT_ID (optional) - Your account ID for organization

Security

• No sensitive data is collected
• Only bot requests are tracked
• The .env file is never committed (add to .gitignore)
• Network failures are handled gracefully and don't affect your app
• Requests have a 2-second timeout to prevent hanging

Uninstall

npm uninstall aigrowth-bot-analytics

The package will clean up by removing itself from package.json scripts. If you need to restore the original scripts, a backup is created at package.json.aigrowth.bak.

License

MIT