Module Settings
Complete guide to configuring the Visitors module settings available in the admin interface.
Configuration Overview
Access module settings at: Configuration → System → Visitors (/admin/config/system/visitors)
Available Settings
Visitor Tracking
Track Visitors
Setting: disable_tracking
Type: Boolean (radio buttons)
Default: false (Enabled)
Options:
- Enabled: Track visitors to the site
- Disabled: Turn off all visitor tracking
Controls whether visitor tracking is active globally.
Tracking Scope
Page Visibility Settings
Pages to Track
Setting: visibility.request_path_pages
Type: Textarea
Default: Empty
Specify which pages to track using Drupal path patterns. Enter one path per line.
Examples:
<front>
/blog
/blog/*
node/*
Path patterns:
- * character is a wildcard
- <front> is the front page
- /blog for specific pages
- /blog/* for all pages under /blog
Tracking Mode
Setting: visibility.request_path_mode
Type: Radio buttons
Options:
- All pages except those listed (0) - Exclude specific pages
- Only the listed pages (1) - Include only specific pages
Role Visibility Settings
Role-Based Tracking Mode
Setting: visibility.user_role_mode
Type: Radio buttons
Options:
- Add to the selected roles only (0)
- Add to every role except the selected ones (1)
Roles to Track
Setting: visibility.user_role_roles
Type: Checkboxes
Default: Empty array
Select which user roles should be tracked (or excluded, depending on the mode above).
User Account Settings
User Account Tracking Mode
Setting: visibility.user_account_mode
Type: Radio buttons
Options:
- Track all users (0)
- Track only users with opt-out permission (1)
- Do not track users with opt-out permission (2)
Exclude User 1
Setting: visibility.exclude_user1
Type: Checkbox
Default: false
Exclude the site's first user (admin) from tracking.
Privacy
Use analytics cookies
Setting: cookies
Type: Checkbox
Default: false
Off by default. When this is off, the tracker calls disableCookies() and
does not set _pk_id, _pk_ses, or _pk_ref. An open visit is matched by
browser fingerprint and IP, so people who share a browser and network can
be counted as one visitor. IP anonymization makes that fingerprint weaker.
Turn this on to store a visitor id in a cookie.
Anonymize IP addresses
Setting: ip_anonymize
Type: Checkbox
Default: false
Store a masked IP address on new visits. Existing visits keep the address already recorded. The selected location plugin receives that stored address.
IP mask length
Setting: ip_mask_length
Type: Radio buttons
Default: 1
How much of the address to remove when anonymization is on:
- 1: last IPv4 octet (
192.168.100.0), or an IPv6/64 - 2: last two IPv4 octets (
192.168.0.0), or an IPv6/48 - 3: last three IPv4 octets (
192.0.0.0), or an IPv6/32
Location
Location plugin
Setting: location_plugin
Type: Radio buttons
Default: browser_language
How the place on a new visit is set.
- None (
none): store no country, city, or coordinates. - Browser language (
browser_language): use the region on the first Accept-Language value.en-USstores the United States. A language with no region stores nothing.
Another module can add a location plugin. It appears in this list. IP geolocation is not included in Visitors.
Entity Counter Settings
Counter Status
Setting: counter.enabled
Type: Checkbox
Default: true
Enable or disable the entity visit counter functionality.
Entity Types to Count
Setting: counter.entity_types
Type: Checkboxes
Default: ['node']
Select which entity types should have visit counters: - Node: Content pages - User: User profiles - Term: Taxonomy terms - Other entity types: As available
Track User ID
Setting: track.userid
Type: Checkbox
Default: true
Track the user ID of authenticated users in visit data. When this is off, the tracker does not send a user id and the stored value is NULL.
Pseudo-anonymize User ID
Setting: track.userid_anonymize
Type: Checkbox
Default: false
Shown when user id tracking is on. Store a stable 32 character pseudonym instead of the Drupal user id. The same person keeps the same value on this site. Existing visits are left unchanged.
Data Retention
Log Retention Period
Setting: flush_log_timer
Type: Select dropdown
Default: 0 (Never)
Automatically discard visitor logs older than the specified time:
Options: - Never (0) - Keep all data - 1 hour (3600) - 3 hours (10800) - 6 hours (21600) - 9 hours (32400) - 12 hours (43200) - 1 day (86400) - 2 days (172800) - 3 days (259200) - 1 week (604800) - 2 weeks (1209600) - 1 month 3 weeks (4838400) - 3 months 3 weeks (9676800) - 1 year (31536000) - 13 months (34214400)
Note: Requires a correctly configured cron maintenance task.
Bot Data Retention
Setting: bot_retention_log
Type: Select dropdown
Default: 0
How to handle bot and crawler visits:
Options: - Keep bot data (0) - Store bot visits normally - Discard bot data (-1) - Don't store bot visits at all - Time-based retention - Same options as log retention above
Display Settings
Script Type
Setting: script_type
Type: Select
Default: minified
Which version of the tracking JavaScript to use: - Minified: Compressed version for production - Full: Uncompressed version for development
Configuration Examples
Basic Site Configuration
# Basic tracking setup
disable_tracking: false
flush_log_timer: 604800 # 1 week retention
bot_retention_log: 0 # Keep bot data
track:
userid: true
counter:
enabled: true
entity_types: ['node']
High-Privacy Configuration
# Privacy-focused setup
disable_tracking: false
flush_log_timer: 86400 # 1 day retention only
bot_retention_log: -1 # Discard bot data
visibility:
user_account_mode: 2 # Don't track users with opt-out
exclude_user1: true # Exclude admin user
track:
userid: false # Don't track user IDs
Content-Only Tracking
# Track only content pages
visibility:
request_path_mode: 1 # Only listed pages
request_path_pages: |
<front>
node/*
user_role_mode: 1 # Exclude selected roles
user_role_roles:
administrator: administrator
counter:
enabled: true
entity_types: ['node']
Development Configuration
# Development site setup
disable_tracking: false
flush_log_timer: 3600 # 1 hour retention
bot_retention_log: 0 # Keep bot data for testing
script_type: full # Unminified JavaScript
Configuration Management
Export Current Settings
# Export visitors configuration
drush config:export --destination=/tmp/config
# View current settings
drush config:get visitors.settings
Import Configuration
# Import configuration
drush config:import --source=/path/to/config
# Set individual values
drush config:set visitors.settings disable_tracking false
Settings in Code
// Get configuration
$config = \Drupal::config('visitors.settings');
$tracking_disabled = $config->get('disable_tracking');
// Programmatically update settings
\Drupal::configFactory()->getEditable('visitors.settings')
->set('flush_log_timer', 86400)
->save();
Validation and Constraints
Required Settings
- All settings have sensible defaults
- No settings are strictly required
- Tracking can be completely disabled
Setting Interactions
- Page visibility: Mode determines how the pages list is interpreted
- Role visibility: Mode determines how the roles list is interpreted
- User tracking: Account mode overrides role settings
- Data retention: Requires cron to be configured
Performance Considerations
High-Traffic Sites
- Shorter retention periods: Reduce database size
- Exclude admin users: Focus on visitor data
- Limit entity types: Track only necessary entities
- Discard bot data: Reduce noise in analytics
Storage Management
- Regular cleanup: Configure appropriate retention periods
- Monitor database growth: Especially with high traffic
- Cron scheduling: Ensure cleanup tasks run regularly
Troubleshooting Settings
Common Issues
No Data Being Collected
- Check
disable_trackingis set tofalse - Verify page visibility settings aren't too restrictive
- Confirm user/role visibility allows tracking
- Check cron is running for data processing
Too Much Data
- Reduce
flush_log_timerfor shorter retention - Set
bot_retention_logto-1to discard bot data - Limit
counter.entity_typesto essential types only - Exclude admin users with
exclude_user1
Performance Problems
- Implement shorter data retention periods
- Consider excluding high-traffic user roles
- Monitor database size and optimize accordingly
Next Steps
- Spam Referrer Detection: Configure referrer filtering
- Search Engines: Set up search engine detection
Note: All settings are stored in the visitors.settings configuration object and can be managed through the admin interface or programmatically via Drupal's configuration API.