Configuration
Learn about all available configuration options for the Insights plugin.
Control Panel
You can manage configuration settings through the Control Panel by visiting Settings → Insights.
Settings
You can define a multi environment aware config in /config/insights.php. Settings defined in the config file override control panel settings.
enabled
Enable or disable all tracking globally.
return [
'*' => [
'enabled' => true,
],
'staging' => [
'enabled' => false, // disable tracking on staging
],
]
respectDoNotTrack
Honor the browser's Do Not Track (DNT) header. When enabled, requests with DNT: 1 header are not tracked.
return [
'*' => [
'respectDoNotTrack' => true, // default
],
]
excludeLoggedInUsers
Skip tracking for authenticated Craft users. Useful to exclude your own team from analytics.
return [
'*' => [
'excludeLoggedInUsers' => false, // default
],
'production' => [
'excludeLoggedInUsers' => true, // don't track logged in users in production
],
]
excludedIpRanges Pro
IP addresses or CIDR ranges to exclude from tracking.
return [
'*' => [
'excludedIpRanges' => [
'192.168.1.1', // single IP
'10.0.0.0/8', // CIDR range
'172.16.0.0/12', // private network
],
],
]
excludedPaths
URL paths to exclude from tracking. Uses prefix matching.
return [
'*' => [
'excludedPaths' => [
'/admin', // matches /admin, /admin/*, etc.
'/cpresources',
'/actions',
'/api', // exclude API endpoints
'/preview', // exclude preview pages
],
],
]
geoIpDatabasePath
Path to the MaxMind GeoLite2-Country database for country tracking.
return [
'*' => [
'geoIpDatabasePath' => '@storage/geoip/GeoLite2-Country.mmdb', // default
],
]
Country data is collected for all editions. Lite users who upgrade to Pro will have historical data available. Without the GeoIP database, country tracking will be silently skipped. See Installation for setup instructions.
dataRetentionDays
Number of days to retain analytics data. Valid range: 1-730 days.
return [
'*' => [
'dataRetentionDays' => 365, // default: keep data for 1 year
],
]
autoCleanup
Automatically delete data older than dataRetentionDays. Cleanup runs daily via Craft's garbage collection.
return [
'*' => [
'autoCleanup' => true, // default
],
]
Cleanup is irreversible. Old data is permanently deleted.
useQueue
Process tracking events asynchronously via Craft's queue system. Recommended for production to minimize page load impact.
return [
'*' => [
'useQueue' => true, // default
],
'dev' => [
'useQueue' => false, // process synchronously in development
],
]
realtimeTtl
How long (in seconds) a visitor is considered "active" for real-time tracking. Valid range: 60-900 seconds.
return [
'*' => [
'realtimeTtl' => 300, // default: 5 minutes
],
]
defaultDateRange
Default date range for the analytics dashboard. Available values: today, 7d, 30d, 90d, 12m.
return [
'*' => [
'defaultDateRange' => '30d', // default
],
]
showRealtimeWidget
Show the real-time visitors widget on the dashboard.
return [
'*' => [
'showRealtimeWidget' => true, // default
],
]
showEntrySidebar
Display analytics statistics in the entry editor sidebar.
return [
'*' => [
'showEntrySidebar' => true, // default
],
]
logLevel
Control the verbosity of plugin logging. Available values: default, debug.
return [
'*' => [
'logLevel' => 'default',
],
'dev' => [
'logLevel' => 'debug', // more detailed logs in development
],
]
Multi-Environment Example
A complete example showing environment-specific configuration:
<?php
// config/insights.php
use craft\helpers\App;
return [
'*' => [
'enabled' => true,
'respectDoNotTrack' => true,
'excludeLoggedInUsers' => false,
'excludedPaths' => ['/admin', '/cpresources', '/actions'],
'dataRetentionDays' => 365,
'autoCleanup' => true,
'useQueue' => true,
'defaultDateRange' => '30d',
],
'dev' => [
'useQueue' => false,
'logLevel' => 'debug',
],
'staging' => [
'enabled' => App::env('INSIGHTS_ENABLED') ?? false,
],
'production' => [
'excludeLoggedInUsers' => true,
],
];