# Drupal Integration

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