KI Bot Tracker for Nuxt 3

A powerful Nuxt 3 module for server-side AI bot detection and tracking. This module integrates with the KI Score platform to provide accurate bot analytics for your Nuxt applications.

Features

• 🤖 Server-side bot detection - 100% accurate tracking
• 🚀 Zero client-side impact - Non-blocking async tracking
• 🔧 Easy integration - Single module installation
• 📊 Real-time analytics - Connects to KI Score dashboard
• 🎯 Nuxt 3/4 compatible - Built for modern Nuxt applications
• 🛡️ Privacy focused - No cookies or client-side tracking
• ⚡ Edge compatible - Works on Vercel, Netlify, Cloudflare

Installation

For local testing, build and install the module:

# Build the module
npm run build

# Install in your Nuxt project
npm install /path/to/nuxt-ki-bot-tracker

Quick Setup

1. Add the module to your nuxt.config.ts:

export default defineNuxtConfig({
  modules: [
    'nuxt-ki-bot-tracker'
  ],
  
  kiBotTracker: {
    siteId: 'your-site-id', // Required: Get this from KI Score dashboard
    apiEndpoint: 'https://api.ki-score.com/track', // Optional
    enabled: true, // Optional, default: true
    debug: false // Optional, default: false
  }
})

2. Get your Site ID from your KI Score dashboard

3. That's it! 🎉 Bot tracking is now active on your site.

Configuration

Basic Configuration

export default defineNuxtConfig({
  kiBotTracker: {
    siteId: 'your-site-id',        // Required: Your KI Score site ID
    enabled: true,                  // Optional: Enable/disable tracking
    debug: false                    // Optional: Enable debug logging
  }
})

Advanced Configuration

export default defineNuxtConfig({
  kiBotTracker: {
    siteId: 'your-site-id',
    apiEndpoint: 'https://api.ki-score.com/track',
    enabled: true,
    debug: false,
    timeout: 2000,                  // Request timeout in milliseconds
    excludePaths: [                 // Paths to exclude from tracking
      '/api/',
      '/_nuxt/',
      '/favicon.ico',
      '/robots.txt'
    ]
  }
})

Environment Variables

You can also use environment variables:

# .env
NUXT_KI_BOT_TRACKER_SITE_ID=your-site-id
NUXT_KI_BOT_TRACKER_ENABLED=true
NUXT_KI_BOT_TRACKER_DEBUG=false

Usage

Automatic Tracking

Once installed, the module automatically tracks all page requests server-side. No additional code required!

Client-side Composable (Optional)

For advanced use cases, you can use the provided composable:

<template>
  <div>
    <button @click="trackCustomEvent">Track Custom Event</button>
    <p>Tracking enabled: {{ isEnabled }}</p>
    <p>Site ID: {{ siteId }}</p>
  </div>
</template>

<script setup>
const { 
  isEnabled, 
  siteId, 
  trackCustomEvent, 
  trackPageView 
} = useKiBotTracker()

const trackCustomEvent = () => {
  trackCustomEvent('button_click', {
    button_name: 'custom_button',
    page: 'home'
  })
}
</script>

Available Composable Methods

const {
  // State
  isEnabled,          // Computed<boolean> - Is tracking enabled
  siteId,            // Computed<string> - Your site ID
  isDebug,           // Computed<boolean> - Is debug mode on
  
  // Methods
  trackPageView,     // () => void - Manual page view tracking
  trackCustomEvent,  // (name: string, props?: object) => void
  trackEvent        // (data?: object) => void - Generic event tracking
} = useKiBotTracker()

How It Works

1. Server Middleware: Intercepts all requests at the Nitro server level
2. Bot Detection: Analyzes user agents, IPs, and request patterns
3. Async Tracking: Sends data to KI Score API without blocking responses
4. Real-time Analytics: View bot activity in your KI Score dashboard

Platform Compatibility

This module works on all Nuxt 3 hosting platforms:

• ✅ Vercel (Edge Runtime)
• ✅ Netlify (Netlify Functions)
• ✅ Cloudflare Workers
• ✅ Node.js servers
• ✅ Static hosting (with API routes)

Development

Building the Module

# Install dependencies
yarn install

# Build for production
yarn build

# Build stub for development
yarn stub

Local Development

To build the module for local testing:

# Build the module
npm run build

# Or create a stub for development
npm run stub

Configuration Reference

| Option | Type | Default | Description | |--------|------|---------|-------------| | siteId | string | Required | Your KI Score site ID | | apiEndpoint | string | https://api.ki-score.com/track | API endpoint for tracking | | enabled | boolean | true | Enable/disable tracking | | debug | boolean | false | Enable debug logging | | timeout | number | 2000 | Request timeout (ms) | | excludePaths | string[] | ['/api/', '/_nuxt/', ...] | Paths to exclude |

Troubleshooting

Common Issues

Module not tracking:

• Verify your siteId is correct
• Check that enabled: true in config
• Enable debug: true to see console logs

Build errors:

• Ensure you're using Nuxt 3.0+
• Check TypeScript configuration

Network requests failing:

• Verify API endpoint is accessible
• Check firewall/proxy settings

Debug Mode

Enable debug mode to see detailed logging:

kiBotTracker: {
  debug: true
}

This will log all tracking attempts to the console.

Support

• 📖 Documentation: KI Score Docs
• 💬 Support: Contact Support
• 🐛 Issues: Report issues through your KI Score dashboard

License

MIT License - see LICENSE file for details.

Built with ❤️ for the Nuxt community by KI Score