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.
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 and obtain a free license key to comply with the CCPA. With the license key, the Geo Targeting add-on by Advanced Ads can upload the files and connect with the database automatically as described in the documentation.
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.
Once the database files are uploaded you can geo-target your ads with the Visitor Conditions meta box on the ad edit screen.
Using a constant
This method is most appropriate when testing on a staging or new website.
You can set the constant
ADVANCED_ADS_GEO_TEST_IP in your
wp-config.php to simulate that traffic from all visitors on your website is coming from a specific IP address.
define( 'ADVANCED_ADS_GEO_TEST_IP', '188.8.131.52' ); // some German IP address
Other resources for testing:
Using a VPN
You can use a so-called VPN to your website from a different “location”. Our team prefers using TunnelBear, which has a free plan large enough for testing.
There are also websites offering a VPN without installing anything or having to create an account. If you try them, then please make sure to test more than one service. We have found some of them to deliver unreliable results.
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.
A good reference point to make sure that you use the correct spelling is the ISO 3166-2 standard for the representation of names of countries and their subdivisions.
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.