=== Explorator ===
Contributors: srwim
Tags: visitor map, analytics, globe, geolocation, hero, realtime, heatmap, gdpr
Requires at least: 5.6
Tested up to: 6.6
Requires PHP: 7.2
Stable tag: 1.4.0
License: MIT
License URI: https://opensource.org/licenses/MIT

A stunning dark, real-time visitor map & 3D globe for the hero space of any corporate WordPress site. Lightweight, privacy-first, deeply themable.

== Description ==

Explorator turns your live traffic into a beautiful dark dotted world map (or rotating 3D globe) that's worthy of a corporate hero section.

* Self-contained dotted world map — no Mapbox/Google tiles, no API keys, no external map assets.
* High-detail coastlines, including the Great Lakes and Michigan.
* Optional 3D globe with auto-rotation, glowing pins and looping ripple pulses.
* Heatmap density render mode (pins, heatmap, or both) for very high-traffic sites.
* Always-on "Online now" tally (visitors active in the last 30 minutes) that auto-refreshes.
* Real-time Live view that polls every few seconds.
* Live tally counters: unique visitors, pageviews, countries.
* Top pages and top referrers, in the (admin-only) on-map data panel and the dashboard.
* Duration controls: live, today, 24 hours, 7 days, 30 days, last year.
* Two IP geolocation providers, selectable in a setup wizard:
  * MaxMind GeoLite2 (offline, instant, no rate limit) — a pure-PHP .mmdb reader is bundled, so no PHP extension is required.
  * Free ip-api.com (zero setup), used as an automatic fallback.
* Deep theming: color presets, individual hex inputs for every layer, match a page CSS variable to your brand, dot/pin sizing, glow, corners, background style.
* Privacy-first: no raw IPs stored (daily-rotating salted hash), Do-Not-Track aware, role exclusions, configurable retention with daily pruning.
* GDPR/CCPA toolkit: consent gate (cookie or JS signal), country-level location coarsening, and a country blocklist.
* Configurable bot, crawler and scraper filtering with a live "bots filtered" counter.
* Scheduled email digests (weekly/monthly) plus traffic-spike and new-country alerts.
* Outbound webhooks (HMAC-signed) for digests, spikes and new-country events.
* Cross-origin embed: a tokenized, CORS-enabled read API to drop the map on any external or non-WordPress site.
* Drop-in tracking for non-WordPress sites: a single <script> tag feeds external sites into this map (grouped by source), no plugin required on the other site.
* WordPress Multisite aware: optional network-wide aggregation across every site.
* CSV export per view (locations / pages / referrers) and a 30-day report export (incl. sources).
* Shortcode `[explorator]` (the original `[explorator]` still works), with per-instance overrides.
* Three-step setup wizard and a live preview built from the real renderer.

== Installation ==

1. In wp-admin go to Plugins → Add New → Upload Plugin, choose explorator.zip, Install, Activate.
2. The Setup Wizard opens automatically. Pick a geolocation provider and a theme.
3. Add `[explorator]` to any page or template. In the block editor, use a Shortcode block.

= MaxMind (optional, recommended for high traffic) =

1. Create a free account at maxmind.com and generate a license key.
2. Download the GeoLite2-City database (`.mmdb`).
3. Upload it anywhere readable on your server (e.g. `/home/you/geoip/GeoLite2-City.mmdb`).
4. In Explorator → Geolocation, choose MaxMind and paste the absolute path.

= Tracking external (non-WordPress) sites =

1. In Explorator → API & Embed, enable "External tracking" and Generate a token.
2. Optionally list the allowed site origins (recommended).
3. Copy the one-line snippet and paste it into the <head> of any external site:

`<script src="https://YOUR-SITE/wp-content/plugins/explorator/assets/js/explorator-track.js" data-endpoint="https://YOUR-SITE/wp-json/explorator/v1/collect" data-token="YOUR-TOKEN" async></script>`

Those visits appear on the same map and under "Traffic sources" in the dashboard and reports.

== Shortcode ==

`[explorator]`
`[explorator view="globe" duration="30d" height="640" preset="aurora"]`
`[explorator render="heat" duration="live"]`
`[explorator scope="network"]`

Attributes: view (map|globe), metric (visitors|pageviews|both), duration (live|today|24h|7d|30d|1y), render (pins|heat|both), height (px), preset (midnight|obsidian|aurora|crimson|custom), scope (site|network).

== Frequently Asked Questions ==

= Does it work outside WordPress / on plain cPanel sites? =
The map widget is the WordPress plugin, but you can feed visits from any external site using the drop-in tracking snippet (see Installation). The external site needs no plugin.

= Who can see the data table? =
The on-map data table (the "hamburger" button and its Locations/Pages/Referrers panel) is shown to administrators only. Regular visitors see the map, counters and controls but not the underlying table.

= What does "Online now" count? =
Distinct visitors active in the last 30 minutes. It is always shown and refreshes on its own (every few seconds in Live mode, about once a minute otherwise).

= Are IP addresses stored? =
No. Visitor identity is a salted SHA-1 hash of IP + user agent that rotates daily and cannot be reversed.

= My own visits don't show up. =
By default administrators and logged-in users are excluded from tracking (Privacy tab). View the site logged-out, or enable "Also count logged-in users".

= I upgraded by overwriting files and nothing records / Online Now stays 0. =
Upgrade to 1.2.1 or newer, which fixes the schema migration so the database columns are added on a file-overwrite upgrade. If you are on 1.2.0, deactivate and reactivate the plugin once to add the missing column (your data is preserved).

== Changelog ==

= 1.4.0 =
* Change: Every internal name now says Explorator: the plugin folder (`explorator/`), the `expl_` options and database tables, the `/explorator/v1` REST routes, the `explorator` text domain, CSS classes, the tracking script (`assets/js/explorator-track.js`), its consent call (`window.exploratorConsent()`) and the webhook header (`X-Explorator-Signature`).
* New: On first load, Explorator imports a site's data from the old `visitor-mapview` plugin folder: it deactivates that plugin, then moves its settings, visit history, geo cache, uploads folder and MaxMind path across. Activate Explorator before deleting the old plugin, because deleting it first erases that data.
* Note: Client sites must re-paste the tracking snippet, and cross-origin embeds must use the new `/explorator/v1/embed` URL. `[visitor_map]` still renders on existing pages.

= 1.3.0 =
* Change: Renamed from Visitor MapView to Explorator. Only the names you see changed: settings, history, the plugin folder, the /vmv/v1 REST routes and client tracking snippets all carried on as before.
* New: `[explorator]` shortcode. `[visitor_map]` keeps working on existing pages.
* Change: Setup and settings now point to the Shortcode block for the block editor.
* Fix: The map legend now totals visitors by country. It used to show the busiest cities labelled only by country, so the same country could appear several times.

= 1.2.6 =
* Fix: Finishing the setup wizard now marks setup complete and opens the Settings page, instead of returning to step 1.
* Fix: Settings page notices (setup complete, settings reset, import, new tokens) are now shown; they were previously dropped.
* Fix: The "online now" and Live window is 30 minutes again, as documented. 1.2.4 had reverted it to 5.
* New: A server-level demo mode used for AROK's own showcases. It is not a setting, and any sample data it shows is always labelled "Demo data" on the map.

= 1.2.5 =
* Change: Relicensed under MIT. Added a LICENSE file with third-party notes.
* Change: Plugin URI and author now point to arok.ai.

= 1.2.3 =
* Change: "Online now" is now always visible (not just in Live mode) and auto-refreshes — every few seconds in Live, about once a minute in other views.
* Change: The "online" / live window is now 30 minutes (was 5), so the tally reflects recent activity rather than only the last few minutes.
* New: The ripple "ping" now loops — it pings, pauses briefly, and pings again — on both the map and the globe.

= 1.2.2 =
* New: The Great Lakes (and Michigan) are now drawn from real high-resolution coastline geometry instead of approximated shapes; the world map resolution was increased to suit.
* Change: The on-map data table ("hamburger" button + panel) is now restricted to administrators.
* Improvement: The world-map data file is cache-busted by version so map changes appear immediately after an upgrade.

= 1.2.1 =
* Fix: Schema migration on a file-overwrite upgrade never ran (the upgrade hook was registered too late to fire), so the 1.2.0 "source" column was not added and new visits failed to record (Online Now / Live stayed 0). The migration now runs reliably and adds any missing columns with explicit ALTERs.

= 1.2.0 =
* New: Drop-in tracking for non-WordPress sites — one <script> tag + a tokenized, CORS-enabled /collect endpoint with an origin allow-list. External visits appear on the same map, grouped by source.
* New: "Traffic sources" breakdown in the dashboard and the 30-day report/CSV.
* New: Higher-resolution world map that now renders the Great Lakes and Michigan.
* New: Ripple pulses on the 3D globe (previously map-only).
* Fix: Live tally counters could freeze at 0 in background/throttled tabs — values now render immediately, with the count-up as a progressive enhancement.
* Fix: The on-map toolbar (the table/hamburger button and panel tabs) was bound twice and cancelled its own clicks — now bound once.
* Fix: The globe rebuilt itself on every data refresh (resetting rotation, churning WebGL) — it now updates points in place, which keeps Live mode smooth.
* Improvement: Dot radius is capped to the grid spacing, so the denser map still reads as dots at any size.

= 1.1.0 =
* New: Real-time Live view with an "online now" tally.
* New: Heatmap density render mode (pins / heat / both).
* New: Top pages and top referrers tracking, in the data panel and dashboard.
* New: GDPR/CCPA consent gate, country-level coarsening, and country blocklist.
* New: Configurable bot/crawler filtering with a filtered-hit counter.
* New: Scheduled weekly/monthly email digests.
* New: Traffic-spike and new-country alerts via email and HMAC-signed webhooks.
* New: Tokenized, CORS-enabled cross-origin embed API for external sites.
* New: WordPress Multisite network-wide aggregation (scope="network").
* New: Per-view CSV export (locations / pages / referrers) and 30-day report export.
* Improvement: Database auto-upgrades on plugin update (adds referrer column).
* Improvement: Larger built-in bot signature list.

= 1.0.0 =
* Initial release.
