Search by

survelium / agent-analytics-laravel

prodixx

Laravel integration for Survelium agent analytics: report AI crawlers and AI-referred visitors server-side.

Package info

github.com/survelium/agent-analytics-laravel

pkg:composer/survelium/agent-analytics-laravel

Statistics

Installs: 7

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

v0.1.0 2026-11-17 12:10 UTC

This package is auto-updated.

Last update: 2026-11-17 12:21:27 UTC


README

Latest Version on Packagist Tests

See which AI crawlers read your Laravel site and how many people AI assistants send you, in Survelium.

AI crawlers (GPTBot, ClaudeBot, PerplexityBot, …) do not run JavaScript, so a JS snippet never sees them. This package adds a middleware that recognises them on the server, plus visitors arriving from ChatGPT, Perplexity, Claude, Gemini or Copilot, and sends them to Survelium in batches from your queue. It is built on survelium/agent-analytics-php.

What leaves your server

Sent Never sent
AI crawler hit time, user agent, path, HTTP status, IP (to verify it is really that crawler) —
Visitor from an AI assistant time, assistant domain (e.g. chatgpt.com), path, user agent IP, full referrer, cookies, session
Every page view by a person a daily count, used for "share of traffic from AI" (other bots — Googlebot, SEO tools, monitors — are not counted) anything about the request

Requirements

PHP 8.2+, Laravel 12 or 13. Laravel 11 still installs, but is no longer tested: every 11.x release has open security advisories, so Composer refuses it by default.

Installation

composer require survelium/agent-analytics-laravel

Add your ingest key (Survelium → AI traffic → Integration) to .env:

SURVELIUM_INGEST_KEY=svk_...

Check it works:

php artisan survelium:flush --force   # sends now; expects "Survelium answered 202"
php artisan survelium:status

That is all. The middleware is added to the web group automatically and does its work in terminate(), after the response has been sent. Without a key nothing is recorded, so local and CI stay quiet.

Before you go live, check

  • Behind Cloudflare or a load balancer: configure Laravel's trusted proxies (see Configuration), or every crawler arrives with the proxy's IP and Survelium cannot verify it.
  • The scheduler runs (* * * * * php artisan schedule:run in cron). Without it data still goes out, but only when new visits arrive.
  • A full-page cache in front of PHP (Varnish, LiteSpeed, Cloudflare "cache everything", spatie/laravel-responsecache served by the web server) means cached pages never reach Laravel, so crawlers reading them are not seen. Exclude AI crawler user agents from that cache.

How it sends

  • Hits are buffered in storage/app/survelium. Every 50 items or 60 seconds a FlushAgentAnalytics job is queued (at most one a minute). On the sync queue it runs after the response, so visitors never wait.
  • survelium:flush is scheduled every five minutes, so the buffer and the daily total also go out on quiet days. This needs the Laravel scheduler (schedule:run in cron) to be running.
  • If Survelium is unreachable the data stays buffered and is retried with back-off; a revoked key or a plan without AI traffic pauses sending without losing data.

Only page views are tracked: GET/HEAD requests that are not XHR, Livewire or prefetch requests.

Configuration

php artisan vendor:publish --tag="survelium-config"
Option Default
ingest_key SURVELIUM_INGEST_KEY Nothing happens while empty.
enabled SURVELIUM_ENABLED, true
track_referrals true false = crawlers only.
middleware_groups ['web'] Set [] and add TrackAgentAnalytics yourself for full control.
deny_paths Telescope, Horizon, Pulse, Debugbar, /up Path prefixes neither reported nor counted.
storage_path storage/app/survelium
queue.connection, queue.name app default SURVELIUM_QUEUE_CONNECTION, SURVELIUM_QUEUE.
schedule true Registers survelium:flush every five minutes.

Behind a load balancer or Cloudflare, configure Laravel's trusted proxies so $request->ip() returns the crawler's real IP; otherwise Survelium cannot verify it.

If you run several web servers, each keeps its own buffer and daily count. Crawler hits add up correctly, but the daily total is taken from one server at a time, so the AI share reads higher than it is.

Testing

composer test

Changelog

See CHANGELOG.

Security

Please report vulnerabilities through GitHub security advisories, not in issues.

License

The MIT License (MIT). See License File.