=== Wheremyflow Analytics ===
Contributors: wheremyflow
Tags: analytics, privacy, gdpr, cnil, sovereign, no-cookie, eu, anti-adblock, self-host, proxy
Requires at least: 5.0
Tested up to: 6.7
Requires PHP: 7.4
Stable tag: 2.0.0
License: MIT
License URI: https://opensource.org/licenses/MIT

Privacy-first, sovereign EU analytics for WordPress. No cookies, no consent banner. Built-in self-host mode that bypasses ad-blockers and Chrome 121+ Tracking Protection without any DNS or Nginx config.

== Description ==

Wheremyflow Analytics is the official WordPress plugin for Wheremyflow — a privacy-first, 100% EU-sovereign web analytics service. The plugin auto-injects a single `<script>` tag on every public page of your site, with two modes :

= Standard mode (3rd-party) =

The classic snippet : `<script defer src="https://wheremyflow.com/w.js" data-site="yoursite.com"></script>`. Simple, lightweight, no server-side load. Drawback : Chrome 121+ in incognito mode and ad-blockers (uBlock Origin, Brave Shields, AdGuard) block requests to third-party "analytics" domains by default. Depending on your audience, **5 to 20 % of sessions silently disappear**.

= Self-host mode (1st-party — built-in proxy) =

**The killer feature.** With one toggle, the plugin :

1. Serves the tracker JS from your own domain via a WordPress route (`/js/flow.js`)
2. Proxies all events (`/api/event`, `/api/ping`, `/api/zone`) through WordPress to wheremyflow.com
3. Caches the tracker JS for 1 hour using the WordPress Transients API (no extra DB load)
4. Forwards `X-Forwarded-For` so wheremyflow.com sees the visitor's real IP for geolocation

The visitor's browser sees **only 1st-party requests** to your own domain. uBlock, Brave, AdGuard and Chrome's Tracking Protection have nothing to filter. No DNS configuration. No Nginx tweak. No cPanel access required. **Works on every WordPress hosting**, including OVH/IONOS/Infomaniak shared plans.

= GDPR / CNIL compliance by construction =

* No cookie set on the visitor's browser
* No persistent identifier (visitor hash rotates daily, salt rotates monthly)
* No cross-site tracking (each site has an isolated identifier space)
* No advertising classification (no UTM parsing, no paid/organic split)
* Honors `Do Not Track`, `Sec-GPC`, and a localStorage opt-out flag
* Compliant with the **CNIL July 2025** referential for audience measurement exempted from consent

= What the plugin does NOT do =

* No phone-home from PHP in standard mode (everything happens client-side)
* No tracking pixel injected by the plugin itself
* No data collection beyond what the standard Wheremyflow JS tracker does
* No third-party scripts loaded
* No SQL table created (the plugin only stores 3 options : domain, dashboard URL, self-host toggle)
* No personal data stored on your WordPress server (in self-host mode, events transit through but are not logged)

= Why use the plugin instead of pasting the snippet manually =

* Survives theme updates (the snippet sits in plugin code, not in `header.php`)
* Settings page with built-in installation test (HTTP probe on home page)
* Self-host mode in one click (impossible without writing PHP yourself)
* Multisite-compatible
* Clean uninstall : no leftover options, no SQL tables, no transient
* MIT-licensed source code under 600 lines, fully auditable

== Installation ==

= Method 1 : upload the ZIP (recommended) =

1. Download `wheremyflow.zip` from your Wheremyflow dashboard (Integration tab → WordPress plugin card).
2. In wp-admin → Plugins → Add New → Upload Plugin, select the ZIP.
3. Activate the plugin.
4. Go to Settings → Wheremyflow.
5. Enter your **site domain** (e.g. `yoursite.com`) — the plugin suggests it automatically based on `home_url()`.
6. Save. Tracking is active immediately on every public page.

= Method 2 : optionally enable self-host mode =

After step 6 above :

7. On the same settings page, toggle **"Enable 1st-party proxy (recommended)"**.
8. Save.
9. Click "Test installation" to confirm everything works.

= Verifying =

Visit any public page of your site. Check the Wheremyflow dashboard's "Verify installation" card. Within a few seconds, your pageview should appear. The integration tab also shows whether self-host mode is detected (1st-party proxy).

== Frequently Asked Questions ==

= Where is my site domain ? =

It's the domain under which your site is publicly accessible (e.g. `mysite.com`, without `www.` and without `https://`). The plugin auto-suggests it based on `home_url()` — usually a single click to fill it in.

= Does the plugin track admin pages ? =

No. The snippet is only injected on public pages (frontend). The wp-admin area is excluded.

= Do I need a cookie banner ? =

**No.** Wheremyflow uses no cookies and is exempted from consent under the CNIL July 2025 referential for audience measurement. Compliance is documented in the Wheremyflow self-assessment PDF (Compliance tab of the dashboard).

= How does self-host mode work ? =

The plugin registers WordPress rewrite rules that map `/js/flow.js` and `/api/{event,ping,zone}` to internal handlers. These handlers fetch the upstream resource from `wheremyflow.com`, cache the tracker JS for 1 hour (Transients API), forward events with the visitor's real IP via `X-Forwarded-For`, and return the response. From the visitor's browser perspective, all traffic is 1st-party — ad-blockers cannot tell it's analytics.

= Will self-host mode slow down my site ? =

Marginally. The tracker JS itself is cached for 1 hour, so most visitors hit a near-instant cache. Each event proxy adds a few milliseconds of server time (an outbound HTTP request to wheremyflow.com), but the visitor's browser uses `sendBeacon()` which is non-blocking — invisible to the user even if the proxy adds 50 ms of latency.

= What happens if wheremyflow.com is down ? =

In self-host mode, if the upstream is unreachable when serving the tracker JS, the plugin returns a no-op stub script (`/* tracker upstream unavailable */`) so your page does not break. Events sent during the outage are lost (no offline queue, by GDPR minimization doctrine). The plugin re-fetches the tracker on the next request once upstream recovers.

= Can I switch back to standard mode ? =

Yes, anytime. Turn off the self-host toggle and save. The plugin flushes the rewrite rules and reverts to injecting the third-party snippet immediately.

= Does the plugin work with caching plugins (WP Rocket, W3 Total Cache, etc.) ? =

Yes. The injection happens in `wp_head` at priority 1, before most caching plugins capture the output. The proxied tracker JS uses standard `Cache-Control: public, max-age=3600`, which CDNs and WP cache plugins handle correctly.

= How do I uninstall completely ? =

Deactivate and delete the plugin from wp-admin → Plugins. The plugin removes its 3 options + tracker cache automatically (multisite-safe). No SQL table to drop. No leftovers.

= Where does the tracker source code live ? =

The plugin proxies the official wheremyflow tracker, served from `wheremyflow.com/w.js` (or your custom dashboard URL). Source code of the tracker : `https://github.com/Fredhugo/wheremyflow/blob/main/src/w.js`. Source code of this plugin : in your `wp-content/plugins/wheremyflow/` folder, under 600 lines of plain PHP, no obfuscation.

== Screenshots ==

1. Settings page : domain field + self-host toggle + status preview + installation test
2. Self-host mode active : visible status pill + 1st-party snippet preview
3. Installation test result : "Tracker correctly installed in self-host mode (1st-party detected)"

== Changelog ==

= 2.0.0 =
* Self-host mode (1st-party proxy) built into the plugin via WordPress REST + rewrite rules
* Installation test button (HTTP probe with i18n result messages)
* French + English UI (extensible : drop a `languages/<locale>.php` file)
* Settings page redesign with the wheremyflow brand palette (dark mode)
* Fix : default dashboard URL was incorrect in v1.0.0 (`app.wheremyflow.com` → `wheremyflow.com`)
* Fix : Plugin URI / Author URI now point to the correct `.com` domain
* CNIL referential update : July 2025 (was 2020-091 in v1.0.0)
* Multisite uninstall improved (cleans up new option keys + transient cache)

= 1.0.0 =
* Initial release. Auto-inject snippet on `wp_head`, settings page, multisite-safe uninstall.

== Upgrade Notice ==

= 2.0.0 =
Major upgrade : self-host mode (anti ad-blocker, anti Chrome Tracking Protection) and several v1 bugs fixed (default URL was broken). Re-save your settings after upgrade — the option key changed from `wml_site_id` to `wmf_site_domain` for clarity.
