Table of Contents
Important changes due to the CCPA
Following the new privacy regulations set by the California Consumer Privacy Act (CCPA), MaxMind has changed the distribution of their free GeoLite2 databases. Since December 30th, 2019, MaxMind requires the users of their GeoLite2 databases to register for a MaxMind account and obtain a license key. This way, MaxMind can ensure, that their service complies with the privacy regulations mandated in the CCPA.
They still offer their GeoLite2 databases free of charge and provide an insightful article about the changes here.
As a new user of Geo Targeting, you have to manually upload the GeoLite2 database files, as described below. If you have installed the database files prior to December 30th, 2019, you should already have them on your server, but you should sign up as a new MaxMind user to download the recent files and comply with the CCPA.
Please be aware that IPs are constantly changing. The more populated the region, the more accurate and constant the geo-targeting is working.
Please note that the used GeoLite2 database by MaxMind might miss IPs especially for small locations and cities. See the upgrade options below.
There is also a list of how accurate the lists are on a city level for each country, see GeoIP2 City Accuracy.
If Cache Busting is used, the Geo-Location Visitor Condition only looks up the location of the visitor ones. This could lead to unexpected behavior when you change the IP address while debugging the option. Make sure to either disable Cache Busting for the placement that uses geo-targeting or remove the
advanced_ads_pro_visitor_referrer cookie after each check.
Geo-targeting test ad
The following ad shows your current position according to the geo-targeting database. It allows you to estimate how far it might be off for your position.
You can download the code of this ad on this page and use it with the Allow PHP option enabled in the Plain text and code ad type.
Database download problems
Please follow these steps to upload the database files of GeoLite2 on your server manually:
- Sign up as a GeoLite2 user at maxmind.com
- Download the databases GeoLite2 City and GeoLite2 Country in the binary format from your MaxMind account (they are provided as GZIP files. You don’t need to download the MD5 files.)
- Unpack the GZIP files. Each archive contains a .mmdb file and two .txt files.
- Upload GeoLite2-City.mmdb and GeoLite2-Country.mmdb into the folder wp-content/uploads/advanced-ads-geo via FTP
Once the database files are uploaded you can geo-target your ads with the Visitor Conditions meta box on the ad edit screen.
You can set the constant ADVANCED_ADS_GEO_TEST_IP in your wp-config.php to simulate a user with a specific IP or when using a local environment.
define( 'ADVANCED_ADS_GEO_TEST_IP', '126.96.36.199' ); // some German IP address
Other resources for testing:
In order to find a potential problem with geo-targeting, you can log all checks made by the plugin.
Add the following line to your wp-config.php file in order to log all checks done by the Geo-Targeting plugin.
define('ADVANCED_ADS_GEO_CHECK_DEBUG', true );
Once the constant is added, all checks will be written into the geo_check.log file in your wp-content folder. You can access it by using the following URL with example.com being your domain: http://www.example.com/wp-content/geo-check.log.
One log entry might look like this:
GEO CHECK (setting|visitor): COUNTRY |DE – REGION | – CITY new york|berlin
The value from the ad settings (left) and the one from the current user (right) are separated by a pipe (|). In the example above, the visitor is in Berlin, Germany (DE) but the ad setting is New York.
Note that COUNTRY and REGION will only be listed here if you provided a value in the geo-targeting Visitor Condition. When you set a continent, it will also be listed next to COUNTRY.
There is no error output if your IP is empty, e.g. when you are in a local environment.
Matching city and state names
Unfortunately, there is no list available with all regions. We suggest to enable geo-targeting debugging and get regions from the log file.
Keep in mind that city and state names must be perfect matches with the geolocation database. Even small differences will result in a broken check.
Example: Bryanskaya Oblast’ and Bryanskaya Oblast’ are not the same string, because of the different apostrophe.
Missing entries and extending the database
The GeoLite2 database created by MaxMind might not be as accurate, especially for smaller areas.
MaxMind offers the GeoIP2 database with better accuracy on a country or city level. See their offers.
In order to use their additional database, just rename it to GeoLite2-City.mmdb for the city level and GeoLite2-Country.mmdb for the country level and replace the file with the same name in wp-content/uploads/advanced-ads-geo in order to use it.