Drupal Integration
Install the Spyglasses Drupal module with Composer to track AI bots and AI referral traffic on Drupal 8.8 through 11, then add your API key.
Spyglasses integrates with Drupal through our official module. The module provides seamless bot detection and AI traffic analytics for Drupal 8.8+, 9.x, 10.x, and 11.x.
Installation
Prerequisites
- Drupal 8.8+ | 9.x | 10.x | 11.x
- PHP 7.4+
- cURL and JSON extensions enabled
- A Spyglasses API key from spyglasses.io
Method 1: Composer (Recommended)
-
Add the module to your project:
-
Enable the module: Navigate to Extend (
/admin/modules) and enable "Spyglasses - AI Traffic Analytics"Or use Drush:
Method 2: Manual Installation
-
Download the latest release from GitHub
-
Extract to your modules directory:
-
Enable the module:
Configuration
1. Get Your API Key
- Sign up for a free account at spyglasses.io
- Copy your API key from the dashboard
2. Configure via Admin UI
- Navigate to Configuration > Web Services > Spyglasses (
/admin/config/services/spyglasses) - Enter your API key
- Configure settings:
- Debug Mode: Enable for troubleshooting
- Auto-sync Patterns: Keep enabled for automatic updates
- Click "Sync Patterns Now" to fetch the latest bot patterns
- Save configuration
3. Configure via Drush
4. Production Configuration
For production environments, configure via settings.php:
Then set the environment variable:
Environment Variables
Set these environment variables for configuration:
| Variable | Description | Default |
|---|---|---|
SPYGLASSES_API_KEY | Your Spyglasses API key | Required |
SPYGLASSES_DEBUG | Enable debug logging | false |
SPYGLASSES_AUTO_SYNC | Auto-sync patterns on startup | true |
SPYGLASSES_CACHE_TTL | Pattern cache TTL in seconds | 86400 (24 hours) |
Deployment
Docker
Add environment variables to your Dockerfile:
Or use docker-compose:
Platform.sh
Add environment variables in your .platform.app.yaml:
Acquia Cloud
Set environment variables in your Acquia Cloud interface or use Cloud Hooks:
Pantheon
Add environment variables through the Pantheon dashboard or use Terminus:
Performance Considerations
The Spyglasses module is designed for high-performance Drupal sites:
- Minimal Overhead: Typically under 1ms per request
- Background Processing: API calls run asynchronously
- Smart Caching: Compiled regex patterns are cached
- CDN Compatible: Works with Varnish, Cloudflare, and other CDNs
Cache Headers
The module automatically sets appropriate cache headers:
- Uses
Vary: User-Agentheaders - Respects existing cache configurations
- Prevents false positives in cached responses
Testing
Verify Installation
-
Check module status:
-
Test bot detection:
-
Check logs:
Test Environment
In your test environment, disable API calls by setting:
Verifying Installation
After deploying your Drupal site with Spyglasses, verify the installation by:
- Check logs for Spyglasses initialization messages (if debug enabled)
- Visit your site with different user agents to generate test traffic
- Monitor your dashboard at spyglasses.io for incoming data
Enable debug mode temporarily to see detection in action:
Troubleshooting
Common Issues
"No API key configured" error
- Ensure your API key is set correctly in configuration
- Check that it doesn't contain invalid characters
- Verify the key is active in your Spyglasses dashboard
Patterns not syncing
- Check network connectivity to spyglasses.io
- Verify your API key is valid
- Enable debug mode to see detailed error messages
Module not detecting traffic
- Verify the module is properly enabled
- Check exclude paths configuration
- Enable debug mode to see processing logs
High memory usage
- Reduce cache TTL in advanced settings
- Check for module conflicts with other contrib modules
Debug Mode
Enable debug mode to see detailed information:
- Go to Configuration > Web Services > Spyglasses
- Check "Enable debug mode"
- Save configuration
- View logs with
drush watchdog:show --filter=spyglasses
Clear Caches
If you're experiencing issues, try clearing caches:
Performance Issues
- Monitor background processing performance
- Check network latency to Spyglasses endpoints
- Review cache TTL settings for optimal performance
Security
- Store API keys securely (use environment variables in production)
- Keep the module updated to the latest version
- Monitor logs for suspicious activity
- Configure appropriate blocking rules in your Spyglasses dashboard
Need help? Contact support@spyglasses.io