Visitor Traffic Real Time Statistics

EXTERNAL SERVICES
This plugin connects to a third-party service to provide visitor geolocation (country/region/city). You can pick which one under *Traffic Stats → Settings → Geolocation provider*:
• freeipapi.com (default since 1.1.9) — for every new visitor, the plugin sends that visitor’s IP address to freeipapi.com’s free JSON endpoint (https://free.freeipapi.com/api/v1/json/…) over an encrypted HTTPS connection to look up its approximate location. No API key, account or signup is required, and freeipapi.com’s free tier permits commercial use. Each IP’s result is cached locally for 7 days (via WordPress transients) so the same visitor is not looked up repeatedly. No cookies, analytics identifiers, or personal data other than the bare IP address are sent.
freeipapi.com: [https://freeipapi.com/](https://freeipapi.com/) — [Terms of Use](https://freeipapi.com/terms) / [Privacy Policy](https://freeipapi.com/privacy)
• ip-api.com (optional, legacy) — the same kind of lookup against ip-api.com’s free JSON endpoint (http://ip-api.com/json/…) instead. Kept as a selectable alternative for sites that were already using it before 1.1.9. Its free, no-API-key tier only serves the endpoint over plain HTTP (not HTTPS) and is licensed for non-commercial use only.
ip-api.com: [https://ip-api.com/](https://ip-api.com/) — [Terms of Service](https://ip-api.com/docs/legal) / [Privacy Policy](https://ip-api.com/docs/legal)

This lookup happens automatically as part of the plugin’s core tracking feature and cannot be turned off without disabling geolocation entirely. Because visitor IP addresses leave your server either way, mention whichever provider you have selected in your site’s own privacy policy. The “Anonymize IP” setting (Settings → Privacy) masks the stored IP address in your own database but does not change what is sent to the geolocation provider for the lookup itself.

FEATURES
Free:
• Recent visitors by IP, with country/region/city
• Live “online now” counter (5-minute window), auto-refreshing
• Browser, OS and device breakdown (pie charts)
• Search-engine totals + latest search keywords
• Top referring sites (paginated)
• Hourly “visits today” table
• 14-day traffic trend line chart
• Traffic by page title
• Summary stats: today / yesterday / 7d / 30d / 12m / total, new vs
returning, bounce rate, average session duration
• World map of visitor locations (Leaflet + OpenStreetMap, no API key)
• Front-end shortcodes: 0 online now, 0
• Bot filtering, IP exclusion list, admin self-exclusion
• Optional IP anonymization, configurable data retention + daily cleanup
• Optional consent-gating: hold off all tracking (and the tracking
cookie) until the visitor has consented, auto-detected from
Complianz or CookieYes, or your own consent tool via a filter
• Scheduled email reports — weekly (every Monday) or monthly (1st of
the month) traffic summary sent to one or more recipients, with a
“send a test now” button
• 404 tracking — which URLs visitors are hitting that don’t exist, how
often, and the page each broken link was followed from
• Outbound link and file-download click tracking, with a combined
“most clicked” table

Pro (locked behind vtrs_is_pro() — wire up your own licensing/payments):
• Full country-level traffic tables (beyond the free top-5 preview)
• Top referring countries
• Full traffic-source breakdown (direct / search / social / referral)
• CSV export of raw visit data
• Unlimited history on every widget

NOTES FOR DEVELOPERS
• Geolocation defaults to the free freeipapi.com JSON endpoint (no
key, HTTPS, rate limited) with ip-api.com selectable as a legacy
alternative — see “External services” above — and caches each IP’s
result for 7 days via transients. Swap in a MaxMind GeoLite2 local
database by adding a case to VTRS_Geo::lookup(). Because the
visitor’s IP is sent to whichever third-party endpoint is selected,
mention it in your site’s own privacy policy.
• When “Require cookie consent” is on, vtrs_has_consent lets you
tell VTRS the answer yourself (return true/false; returning
null, the default, falls through to the built-in Complianz/
CookieYes detection):
add_filter( ‘vtrs_has_consent’, fn() => my_plugin_has_analytics_consent() );
• vtrs_is_pro() is a filterable gate (vtrs_is_pro) with no opinion
of its own about licensing — it returns false unless something
hooks the filter and says otherwise. The **Visitor Traffic Stats
Pro** add-on (separate plugin, sold/activated independently) is what
actually hooks it: it owns license-key storage/validation and
returns true once a site has a valid, active license. This plugin
never needs to know how licensing works — it only asks “am I
unlocked?” via the filter. Point a license-checking plugin at your
own backend (a self-hosted REST endpoint, EDD Software Licensing,
Freemius, etc.) and it will “just work” here.
• Two data-safety rules for anything gated behind vtrs_is_pro():
never wp_send_json_success() / never echo the *unlocked* rows into
a page’s HTML (even visually hidden) unless the current request is
actually Pro — query with a free-tier row cap instead of fetching
everything and hiding the extra rows with CSS.
• All visit data lives in {prefix}vtrs_visits and {prefix}vtrs_online},
created via dbDelta() on activation. {prefix}vtrs_daily_stats holds
one pre-aggregated (visitors, visits) row per completed calendar day —
see VTRS_DB::aggregate_day() / catch_up_daily_stats() — and is
rebuildable at any time by truncating it and letting the daily cron
(or VTRS_DB::catch_up_daily_stats()) repopulate it from raw history.
• 404 hits and outbound/download clicks share one vtrs_events table,
keyed by event_type — a deliberately generic shape so the next event
type is a new string rather than another schema migration. URLs are
grouped on url_hash (an md5 of the URL) because the full URL is a
TEXT column and can’t be indexed or grouped on efficiently.
• Uninstalling the plugin removes its options; it only drops the data
tables if you define VTRS_REMOVE_DATA_ON_UNINSTALL as true in
wp-config.php first.