Drupal Integration

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)

1. Add the module to your project:

   composer require spyglasses/spyglasses

2. Enable the module: Navigate to Extend (/admin/modules) and enable "Spyglasses - AI Traffic Analytics"

   Or use Drush:

   drush en spyglasses

Method 2: Manual Installation

1. Download the latest release from GitHub

2. Extract to your modules directory:

   # Extract to modules/contrib/spyglasses/

3. Enable the module:

   drush en spyglasses

Configuration

1. Get Your API Key

1. Sign up for a free account at spyglasses.io
2. Copy your API key from the dashboard

2. Configure via Admin UI

1. Navigate to Configuration > Web Services > Spyglasses (/admin/config/services/spyglasses)
2. Enter your API key
3. Configure settings:
   • Debug Mode: Enable for troubleshooting
   • Auto-sync Patterns: Keep enabled for automatic updates
4. Click "Sync Patterns Now" to fetch the latest bot patterns
5. Save configuration

3. Configure via Drush

# Set API key
drush config:set spyglasses.settings api_key "your-api-key-here"
 
# Enable debug mode (optional)
drush config:set spyglasses.settings debug_mode true
 
# Sync patterns
drush php:eval "\Drupal::service('spyglasses.pattern_sync')->syncIfNeeded();"

4. Production Configuration

For production environments, configure via settings.php:

// In your settings.php file
$config['spyglasses.settings']['api_key'] = getenv('SPYGLASSES_API_KEY');
$config['spyglasses.settings']['debug_mode'] = FALSE;
$config['spyglasses.settings']['auto_sync'] = TRUE;

Then set the environment variable:

export SPYGLASSES_API_KEY="your-api-key-here"

Environment Variables

Set these environment variables for configuration:

Deployment

Docker

Add environment variables to your Dockerfile:

ENV SPYGLASSES_API_KEY=your_api_key_here
ENV SPYGLASSES_DEBUG=false

Or use docker-compose:

services:
  drupal:
    image: drupal:latest
    environment:
      - SPYGLASSES_API_KEY=your_api_key_here
      - SPYGLASSES_DEBUG=false

Platform.sh

Add environment variables in your .platform.app.yaml:

variables:
  env:
    SPYGLASSES_API_KEY: your_api_key_here
    SPYGLASSES_DEBUG: false

Acquia Cloud

Set environment variables in your Acquia Cloud interface or use Cloud Hooks:

export SPYGLASSES_API_KEY=your_api_key_here

Pantheon

Add environment variables through the Pantheon dashboard or use Terminus:

terminus env:set mysite.dev SPYGLASSES_API_KEY your_api_key_here

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-Agent headers
• Respects existing cache configurations
• Prevents false positives in cached responses

Testing

Verify Installation

1. Check module status:

   # Verify module is enabled
   drush pm:list | grep spyglasses
    
   # Check configuration
   drush config:get spyglasses.settings

2. Test bot detection:

   # Test with ChatGPT user agent
   curl -H "User-Agent: ChatGPT-User/1.0" http://your-drupal-site.com/
    
   # Test with GPTBot
   curl -H "User-Agent: GPTBot/1.0" http://your-drupal-site.com/
    
   # Test AI referrer
   curl -H "Referer: https://chat.openai.com/" http://your-drupal-site.com/

3. Check logs:

   # View Spyglasses logs
   drush watchdog:show --filter=spyglasses
    
   # View in real-time
   drush watchdog:tail --filter=spyglasses

Test Environment

In your test environment, disable API calls by setting:

// In settings.local.php or test settings
$config['spyglasses.settings']['api_key'] = NULL;
$config['spyglasses.settings']['auto_sync'] = FALSE;

Verifying Installation

After deploying your Drupal site with Spyglasses, verify the installation by:

1. Check logs for Spyglasses initialization messages (if debug enabled)
2. Visit your site with different user agents to generate test traffic
3. Monitor your dashboard at spyglasses.io for incoming data

Enable debug mode temporarily to see detection in action:

drush config:set spyglasses.settings debug_mode true

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:

1. Go to Configuration > Web Services > Spyglasses
2. Check "Enable debug mode"
3. Save configuration
4. View logs with drush watchdog:show --filter=spyglasses

Clear Caches

If you're experiencing issues, try clearing caches:

drush cache:rebuild

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