Smart IP
Smart IP identifies visitor's geographical location (longitude/latitude, country, region, city, postal code) based on IP address, storing data in session and user data service.
smart_ip
Install
composer require 'drupal/smart_ip:8.x-4.2'
Overview
Smart IP is a comprehensive geolocation module that determines a visitor's geographical location based on their IP address. The module identifies country (ISO 3166 2-character code), region, city, postal code, latitude, longitude, time zone, and whether the user is from an EU/GDPR country.
Location data is stored in PHP session variables ($_SESSION['smart_ip']) and Drupal's user data service (module='smart_ip', name='geoip_location'). The storage can be selectively disabled by role. The module provides an extensible plugin architecture through data source submodules, allowing administrators to choose from various geolocation providers including MaxMind GeoIP2 (binary database and web service), IP2Location, IPInfoDB, and Abstract IP Geolocation.
Smart IP also includes fallback mechanisms using server-side geolocation headers from Apache mod_geoip, nginx X-GeoIP-Country, Cloudflare IP Geolocation, and Akamai EdgeScape when the primary data source fails. The module offers a Countries condition plugin for block visibility control, debug mode for IP spoofing during testing, and GDPR compliance features to prevent storing location data for visitors from EU countries.
Features
- IP-based geolocation identifying country, region, city, postal code, latitude, longitude, and time zone
- Multiple pluggable data sources: MaxMind GeoIP2 (binary database and web service), IP2Location binary database, IPInfoDB web service, Abstract IP Geolocation web service
- Device Geolocation submodule using W3C Geolocation API with Google Geocoding for enhanced precision (street number, neighborhood, administrative areas)
- Automatic fallback to server-side geolocation headers (mod_geoip, X-GeoIP-Country, Cloudflare, Akamai EdgeScape)
- Role-based geolocation configuration - select which user roles should be geolocated
- GDPR compliance option to prevent storing location data for visitors from EU/GDPR countries
- Debug mode with per-role IP address spoofing for testing purposes
- Page-specific geolocation - configure which pages should trigger geolocation updates
- IP exclusion list to skip lookup for specific IP addresses
- Countries condition plugin for block visibility based on visitor's country
- Automatic database updates via cron for binary database data sources
- Manual IP lookup tool in admin interface
- Time zone detection with configurable format (identifier or UTC offset)
- Integration with Geo Time Zone module for accurate timezone determination
- Location data available to JavaScript via drupalSettings.smartIp
- Supports both IPv4 and IPv6 addresses
- User location saved on registration with option to preserve original location
Use Cases
Country-based content restriction
Use the Countries condition plugin to show or hide blocks based on visitor's country. Configure block visibility at /admin/structure/block, add the Countries condition, and select which countries should see the block. Useful for regional promotions, legal compliance notices, or localized content.
Geotargeted advertising
Access visitor location data via drupalSettings.smartIp in JavaScript or \Drupal::service('smart_ip.smart_ip_location')->getData() in PHP to serve location-specific advertisements or offers.
GDPR compliance for EU visitors
Enable 'Don't save location details of visitors from GDPR countries' option to prevent storing personal location data for visitors from EU member countries and territories that follow GDPR regulations.
Performance optimization for cached sites
When using page caching, enable Device Geolocation's 'Use AJAX in user's geolocation checking' option to perform geolocation checks asynchronously without breaking page cache.
Development and testing
Use the debug mode feature to test geolocation functionality with specific IP addresses. Enable debug mode for specific roles and enter test IP addresses to simulate visitors from different locations.
User registration location tracking
Enable 'Save user's location details upon creation' to store the original location where each user registered. This data is stored separately and preserved even when the user's current location changes.
High-traffic site with local database
Use MaxMind GeoIP2 or IP2Location binary database submodules for high-traffic sites to avoid external API rate limits and latency. Enable automatic database updates via cron to keep data current.
Tips
- Use the Manual lookup tool on the admin page to test IP addresses and verify your data source is working correctly.
- For production sites with high traffic, prefer binary database sources over web services to avoid API rate limits and external dependencies.
- Configure 'Acquire/update user's geolocation on specific Drupal native pages' to limit geolocation overhead to only necessary pages.
- Combine with Views and other modules that support conditions to create location-aware content listings.
- The module exposes location data to JavaScript via drupalSettings.smartIp, enabling client-side geotargeting without additional AJAX calls.
- When debugging, remember that debug mode IP takes precedence over the actual visitor IP - disable it before going to production.
Technical Details
Admin Pages 1
/admin/config/people/smart_ip
Main configuration page for Smart IP module. Configure data source selection, roles to geolocate, debug settings, and perform manual IP lookups.
Permissions 1
Hooks 1
hook_smart_ip_user_save_alter
Allows modules to modify the user's location data before it is saved to session and user data.
Troubleshooting 6
Ensure 'anonymous' role is selected in 'Roles to Geolocate' setting. Note that this adds substantial overhead as every anonymous request triggers geolocation lookup.
Verify your private file system path is configured in settings.php. Upload the database file to the 'smart_ip' folder within your private files directory. Check file permissions.
Verify your data source is properly configured with valid API keys or database files. Try the Manual lookup feature to test if the data source is responding correctly.
Ensure Google Maps API key is configured. Check that the page is served over HTTPS (required for W3C Geolocation API). Verify JavaScript is enabled and not blocked.
Check if the user's IP address is in the exclusion list. Verify the current page is in the allowed pages list (if configured). Clear browser cookies/session or test with a different browser.
Verify your license key and account ID are correct. Check that cron is running properly. Ensure sufficient disk space and write permissions in the private files directory.
Security Notes 5
- The 'administer smart_ip' permission is marked as restricted access - only grant it to trusted roles.
- API keys for web services are stored in configuration - ensure config files are properly secured and not exposed in version control.
- Binary database files should be stored in the private files directory, not the public files directory.
- When using debug mode, be aware that the configured test IP may be logged or stored - use non-sensitive test IPs.
- GDPR compliance features help meet regulatory requirements, but additional measures may be needed for full compliance.