Prerequisites

Before installing the tracking plugin, you need to create a Tracking key from the AI Labs Audit dashboard. This will give you your 4 credentials:

1

Go to API & Integrations

Log in to your AI Labs Audit account and go to the API & Integrations page.

2

Create a Tracking key

Click Create a key, select role Client, choose the client, then select key type Tracking IA (trk_live_...) and confirm.

3

Copy your 4 credentials

A dialog will display your credentials. Copy them all immediately, the HMAC Secret will never be shown again:

API Key — your unique tracking key (format: trk_live_...)
HMAC Secret — secret key to sign payloads (never expose client-side)
Client ID — your client identifier that links data to your account
API URL — the endpoint: https://ailabsaudit.com/api/v1

Important

The HMAC Secret is only shown once at creation time. If you lose it, you will need to create a new Tracking key.

GDPR Compliant

The tracker collects no personal data. It only detects AI bot user-agents and AI referrer domains. No cookies, no IP tracking, no fingerprinting.

WordPress Plugin

The WordPress plugin is the easiest way to get started. It handles everything automatically: AI bot detection, event buffering and scheduled sending.

Installation

You have two options to install the plugin:

1

Option A: Upload via FTP / File Manager

Download the plugin from GitHub and upload the ailabsaudit-tracker folder to /wp-content/plugins/.

2

Option B: Install via WordPress Admin

Go to Plugins > Add New > Upload Plugin, select the ZIP file and click Install Now.

Configuration

3

Activate the plugin

Go to Plugins in your WordPress admin, find AI Labs Audit Tracker and click Activate.

4

Enter your credentials

Navigate to Settings > AI Labs Audit and fill in your API Key, HMAC Secret, Client ID and API URL.

5

Test the connection

Click the "Test Connection" button to verify that your credentials are correct and events can be sent.

How it works

< 1ms detection

Bot detection adds less than 1 millisecond per page load.

Event buffering

Events are buffered in WP transient and sent via WP-Cron every 5 minutes.

Daily refresh

Bot signatures and referrer domain lists are refreshed daily from the API.

Object cache compatible

Works seamlessly with Redis, Memcached and other object caching solutions.

GDPR Compliant

The plugin collects no personal data whatsoever. It only detects AI bot user-agent strings and AI referrer domains. No cookies, no IP addresses, no tracking of real visitors.

PHP Generic

For non-WordPress PHP sites, use the standalone PHP tracker with built-in auto-detection. Install it via Composer or by copying the single file.

Installation

Composer

composer require ailabsaudit/tracker

Alternatively, download AilabsTracker.php from the GitHub repository and include it directly.

Usage example

PHP

use AilabsAudit\Tracker\AilabsTracker;

$tracker = new AilabsTracker(
    apiKey: 'your-api-key',
    apiSecret: 'your-hmac-secret',
    clientId: 'your-client-id',
    apiUrl: 'https://ailabsaudit.com/api/v1',
    enableDetection: true,
    bufferStorage: '/tmp/ailabs_buffer.json'
);

// Call at the top of your front controller
$tracker->detect();

How it works

Auto-detection is opt-in (enableDetection: false by default) for backward compatibility. When enabled, detect() automatically identifies AI bots and referrers from the current request.
Buffer: events are persisted to a JSON file (LOCK_EX for concurrency safety) and flushed in batch.
API refresh: bot signatures and referrer domain lists are automatically refreshed from the API (24h TTL, ETag support).

Requirements

PHP 7.4+, ext-curl, ext-json.

Node.js

For Node.js backends (Express, Fastify, Next.js, etc.), use the official npm package with built-in Express middleware and auto-detection.

Installation

npm

npm install @ailabsaudit/tracker-node

Alternatively, copy src/index.js from the GitHub repository.

Usage example

JavaScript

const { AilabsTracker, createMiddleware } = require('@ailabsaudit/tracker-node');

const tracker = new AilabsTracker({
  apiKey: 'your-api-key',
  apiSecret: 'your-hmac-secret',
  clientId: 'your-client-id',
  apiUrl: 'https://ailabsaudit.com/api/v1',
  enableDetection: true,
});

// Express middleware — auto-detects bots & referrals
app.use(createMiddleware(tracker));

// Graceful shutdown — flushes remaining buffer
process.on('SIGTERM', () => tracker.shutdown());

How it works

Auto-detection is opt-in (enableDetection: false by default). When enabled, the middleware automatically detects AI bots and referrers on each request.
Buffer: in-memory buffer (max 500 events), flushed every 5 min, debounce 30s. Retry x3 on 5xx/429 errors.
API refresh: bot signatures and referrer lists are refreshed from the API (24h TTL, ETag support).

Graceful shutdown

tracker.shutdown() flushes remaining buffered events and stops all timers. Essential to avoid losing events when your process stops.

Requirements

Node.js 14+. No external dependencies.

Python

For Python backends (Django, Flask, FastAPI, etc.), use the pip package with WSGI/ASGI middleware and auto-detection.

Installation

pip

pip install ailabsaudit-tracker

Alternatively, copy tracker.py from the GitHub repository.

Usage example

Python (Flask)

from ailabsaudit_tracker import AilabsTracker, WsgiMiddleware

tracker = AilabsTracker(
    api_key="your-api-key",
    api_secret="your-hmac-secret",
    client_id="your-client-id",
    api_url="https://ailabsaudit.com/api/v1",
    enable_detection=True,
)

# WSGI middleware — detects AI bots and referrals automatically
app.wsgi_app = WsgiMiddleware(app.wsgi_app, tracker)

# Graceful shutdown — flush remaining buffer
import atexit
atexit.register(tracker.shutdown)

How it works

Auto-detection is opt-in (enable_detection=False by default). Once enabled, the middleware automatically detects AI bots and referrers on every request.
Buffer: thread-safe in-memory buffer (max 500 events), flushed every 5 min via a daemon timer thread. Retry x3 on 5xx/429 errors.
API refresh: bot signatures and referrer lists are refreshed from the API in a background thread (TTL 24h, ETag support).

Graceful shutdown

tracker.shutdown() flushes the remaining buffered events and stops all timer threads. Essential to avoid losing events when stopping your process (Gunicorn, uWSGI, etc.).

Requirements

Python 3.8+. No external dependencies. Compatible with WSGI (Flask, Django) and ASGI (FastAPI, Starlette).

Cloudflare Worker

Deploy the tracker as a Cloudflare Worker to intercept and analyze requests at the edge, with zero impact on your origin server.

Installation

1

Install Wrangler

If you don't have Wrangler installed yet:

Terminal

npm install -g wrangler

2

Configure wrangler.toml

Clone the GitHub repository and edit wrangler.toml to set the API_URL variable.

wrangler.toml

[vars]
API_URL = "https://ailabsaudit.com/api/v1"

3

Set secrets

Add your credentials as Cloudflare Worker secrets (they are never exposed in code):

Terminal

wrangler secret put API_KEY
wrangler secret put API_SECRET
wrangler secret put CLIENT_ID

4

Deploy

Deploy the Worker to Cloudflare's edge network:

Terminal

wrangler deploy

How it works

Edge detection

Intercepts GET requests at Cloudflare's edge, before they reach your origin server.

90+ bot signatures

Detects over 90 AI bot user-agent signatures including GPTBot, ClaudeBot, Bingbot AI, etc.

30+ AI referrers

Identifies traffic from 30+ AI referrer domains like ChatGPT, Perplexity, You.com, etc.

Fire-and-forget

Events are sent asynchronously via ctx.waitUntil() with zero latency impact.

Dynamic refresh

Bot signatures and AI referrer lists are refreshed dynamically from the API via the Cloudflare Cache API (TTL 24h). If the API is unreachable, the Worker falls back to its hardcoded lists bundled at deploy time.

JavaScript Pixel Tag

A lightweight client-side tracker (< 2 KB) that you add as a single script tag. Ideal for static sites, landing pages or when you don't have server-side access.

Installation

Add the following script tag to your HTML, just before the closing </body> tag:

HTML

<script src="/path/to/tracker.js"
  data-tracker-id="YOUR_TRACKER_ID"
  data-api-url="https://ailabsaudit.com/api/v1/collect">
</script>

What it tracks

page_view

Automatically tracks each page view with URL and referrer information.

page_leave

Captures page leave events with time spent on page and scroll depth.

click

Tracks click events on links and interactive elements.

Security note

Client-side payloads are unsigned (HMAC secrets cannot be exposed in the browser). Payloads are validated server-side by origin domain. Make sure your domain is registered in your AI Labs Audit settings.

Verification

Once you've deployed the tracker, verify that everything is working correctly from your AI Labs Audit dashboard.

1

Open your dashboard

Log in to your AI Labs Audit account and navigate to the Tracking page for your client.

2

Check for bot crawls

AI bot crawls should start appearing within minutes of deployment. Look for entries from GPTBot, ClaudeBot, Bingbot and other AI crawlers.

3

Check for AI referrals

Traffic referred from AI platforms (ChatGPT, Perplexity, Copilot, etc.) will also appear in the dashboard as they occur.

4

Review event details

Click on any event to see full details: user-agent, URL crawled, timestamp, status code and response size.

Tip

If you don't see data after a few minutes, double-check your credentials in the plugin settings and ensure your server can reach https://ailabsaudit.com/api/v1. For WordPress, verify that WP-Cron is running correctly.

Install the AI Labs Audit Tracking Plugin

Table of contents

Prerequisites

Go to API & Integrations

Create a Tracking key

Copy your 4 credentials

Important

GDPR Compliant

WordPress Plugin

Installation

Option A: Upload via FTP / File Manager

Option B: Install via WordPress Admin

Configuration

Activate the plugin

Enter your credentials

Test the connection

How it works

< 1ms detection

Event buffering

Daily refresh

Object cache compatible

GDPR Compliant

PHP Generic

Installation

Usage example

How it works

Requirements

Node.js

Installation

Usage example

How it works

Graceful shutdown

Requirements

Python

Installation

Usage example

How it works

Graceful shutdown

Requirements

Cloudflare Worker

Installation

Install Wrangler

Configure wrangler.toml

Set secrets

Deploy

How it works

Edge detection

90+ bot signatures

30+ AI referrers

Fire-and-forget

Dynamic refresh

JavaScript Pixel Tag

Installation

What it tracks

page_view

page_leave

click

Security note

Verification

Open your dashboard

Check for bot crawls

Check for AI referrals

Review event details

Tip

Ready to track AI visibility?

Ready to audit your AI visibility?