Last updated
Revenue First Analytics determines a visitor’s country with a MaxMind GeoLite2 database stored on your own server: its own GeoLite2-City database when one has been downloaded, otherwise the GeoLite2-Country database that WooCommerce downloads. The IP address is used for that lookup only and is never stored or sent to an outside service. Without a database, the country stays empty.
How is the visitor’s country determined?
When the tracker reports a pageview, the plugin takes the visitor’s IP address from the request and looks it up locally, in this order:
- The plugin’s own GeoLite2-City database in
wp-content/uploads/rfa-geoip/GeoLite2-City.mmdb, which returns country, region and city. - WooCommerce’s GeoLite2-Country database in
wp-content/uploads/woocommerce_uploads/, which returns the country only. If the file is missing, the plugin asks WooCommerce’s own geolocation class, without allowing it to call a remote API.
There is no remote fallback. Private, loopback and reserved addresses (for example a local development site) are skipped. The result for an IP is cached for a day in the WordPress object cache so repeat pageviews do not repeat the lookup.
Which IP address is used matters on hosts behind a CDN or load balancer. The plugin reads, in order, the CF-Connecting-IP header (Cloudflare), X-Real-IP, the first address in X-Forwarded-For, and finally the direct connection address. The same IP goes into the cookieless visitor hash described in How Revenue First Analytics Works.
Is the IP address stored?
No. The IP address is used in memory for the lookup and for the daily visitor hash, and then discarded. For anonymous visitors (Privacy mode, or Consent mode before consent) the address is truncated before the lookup, to the first three octets of an IPv4 address or the first 48 bits of an IPv6 address, and only the country is kept. Region and city are resolved for identified visitors only. See Cookies, Data Stored and Data Retention for the full list of what is kept.
Where does the country appear in the dashboard?
The Geography card has a Country tab with visitors, revenue and orders per country, and clicking a country filters the whole dashboard (see Filtering Reports by Channel, Page, Country or Device). Region and City tabs exist in the code but are not shown in this version. A separate “customer country” is stored with each order from the billing address; it does not depend on the GeoIP lookup.
How do I get a GeoLite2 database?
In version 1.4.0 the plugin’s own download card (GeoIP Database, with a MaxMind License Key field and a Download button) is not shown on the Settings screen, so the practical route is WooCommerce:
- Create a free MaxMind account and generate a license key at maxmind.com.
- In WordPress go to WooCommerce, Settings, Integration, MaxMind Geolocation, enter the key and save. WooCommerce downloads the GeoLite2-Country database into
wp-content/uploads/woocommerce_uploads/. - Nothing to configure in Revenue First Analytics. The plugin finds the file through WooCommerce’s MaxMind settings and starts using it for the next pageviews.
WooCommerce’s database gives country only. The plugin’s own GeoLite2-City download, which adds region and city, is planned for a later release together with the Region and City tabs. Sites without WooCommerce (Easy Digital Downloads only) currently have no way to add a database from the admin, and countries stay empty.
How often is the database updated?
WooCommerce updates the database it downloaded on its own schedule; the plugin reads whatever file is there. For the plugin’s own GeoLite2-City database, a weekly WordPress cron event named rfa_geoip_update is scheduled after a successful download. It re-downloads the database only when the stored MaxMind license key exists and the file is more than seven days old. Because the download card is hidden in this version, this schedule is not active on a normal 1.3.0 install.
Common issues
| Symptom | Cause | Fix |
|---|---|---|
| No countries at all | No GeoLite2 database on the server, or the site runs on a local or private network address. | Add a MaxMind key in WooCommerce as described above. Local addresses are skipped by design. |
| Every visitor shows the same country | A proxy, load balancer or CDN that does not pass the visitor’s address in one of the headers the plugin reads, so every request looks like it comes from the proxy. This also makes all anonymous visitors share one visitor ID. | Configure the proxy to send X-Forwarded-For or X-Real-IP (Cloudflare sends CF-Connecting-IP automatically), or have a developer return the right address with the wpgens_rfa_client_ip filter. |
| A visitor’s country is wrong | VPNs, mobile carrier networks and outdated databases. | Keep the WooCommerce database updated; occasional mismatches are normal for any IP database. |
| Region and City are empty | The WooCommerce database is country-only, and the Region and City tabs are hidden in this version. | No action possible yet. |
| Country missing for some visitors but not others | Anonymous visitors are looked up with a truncated address, which can fall outside the database’s ranges more often than a full address. | Expected in Privacy mode and before consent; see Choosing a Privacy Mode. |
For developers, the filter looks like this:
add_filter( 'wpgens_rfa_client_ip', function ( $ip ) {
return $_SERVER['HTTP_TRUE_CLIENT_IP'] ?? $ip;
} );