# 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](https://packagist.org/packages/spyglasses/spyglasses). 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](https://www.spyglasses.io)

### Method 1: Composer (Recommended)

1. **Add the module to your project**:
   ```bash
   composer require spyglasses/spyglasses
   ```

2. **Enable the module**:
   Navigate to **Extend** (`/admin/modules`) and enable "Spyglasses - AI Traffic Analytics"
   
   Or use Drush:
   ```bash
   drush en spyglasses
   ```

### Method 2: Manual Installation

1. **Download the latest release** from GitHub
2. **Extract to your modules directory**:
   ```bash
   # Extract to modules/contrib/spyglasses/
   ```

3. **Enable the module**:
   ```bash
   drush en spyglasses
   ```

## Configuration

### 1. Get Your API Key

1. Sign up for a free account at [spyglasses.io](https://www.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

```bash
# 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`:

```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:
```bash

```

## 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:

```dockerfile
ENV SPYGLASSES_API_KEY=your_api_key_here
ENV SPYGLASSES_DEBUG=false
```

Or use docker-compose:

```yaml
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`:

```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:

```bash

```

### Pantheon

Add environment variables through the Pantheon dashboard or use Terminus:

```bash
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**:
   ```bash
   # Verify module is enabled
   drush pm:list | grep spyglasses
   
   # Check configuration
   drush config:get spyglasses.settings
   ```

2. **Test bot detection**:
   ```bash
   # 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**:
   ```bash
   # 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:

```php
// 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](https://www.spyglasses.io) for incoming data

Enable debug mode temporarily to see detection in action:

```bash
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:

```bash
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
