=== Dreamfox Form Analytics ===
Contributors: dreamfox
Tags: form analytics, contact form 7, elementor forms, conversion, funnel
Requires at least: 6.5
Tested up to: 7.0
Requires PHP: 8.1
Stable tag: 1.0.1
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Privacy-friendly form analytics: see where visitors abandon your forms — views, starts, submissions, per-field drop-off and validation errors.

== Description ==

**Dreamfox Form Analytics** shows you how visitors actually use your WordPress forms — and, more importantly, where they give up. Every form gets a clear funnel from *viewed* → *started* → *submitted*, with per-field drop-off, validation-error counts, time spent per field and day/week/month trends.

The plugin is **privacy-friendly by design**: it never stores what visitors type, who they are, or where they come from. No cookies, no IP addresses, no user agents, no form field contents — only anonymous interaction metadata under a random identifier that lives for a single page view.

= What you see per form =

* Views, starts, successful submissions
* Start rate, completion rate, conversion and abandonment rate
* Drop-off per field: which field is the last one visitors touch before leaving
* Validation errors per field
* Average time per form and per field
* Desktop / tablet / mobile breakdown (optional)
* Trends per day, week or month

= Notable fields, computed locally =

The dashboard flags problem fields with plain-language conclusions such as *"Field 'phone-number' causes 24% of all form abandonment."* These insights come from fixed, deterministic rules computed on your own server — no external AI service, no data leaves your site.

= Supported form plugins =

* **Contact Form 7**
* **Elementor Forms** (Elementor Pro)

Active form plugins are detected automatically; nothing breaks when one is missing. The integration layer is prepared for more form plugins (WPForms, Gravity Forms, Fluent Forms, Formidable Forms, Ninja Forms) in future releases.

= Privacy by design =

* **Never stored:** names, email addresses, phone numbers, IP addresses, form field values, cookies, raw user agents.
* **Anonymous sessions:** a random identifier per form per page view, generated in the browser, never linked to a person.
* **Retention you control:** 7, 30, 90, 180 or 365 days — older data is deleted automatically every day.
* **Do Not Track / Global Privacy Control:** respected in the browser *and* enforced again on the server (enabled by default).
* **Exclusions:** keep administrators (default) and optionally all logged-in users out of the statistics.
* **Clean uninstall:** data is kept by default so you can reinstall; opt in to delete everything on uninstall.
* **WordPress privacy tools:** suggested privacy-policy text and a personal-data eraser are registered.

= Built for performance =

* One small dependency-free tracking script (~4 KB gzipped), loaded only when tracking is active and a supported form plugin is present.
* Events are batched and sent via `sendBeacon`/`fetch keepalive` — no request storm, nothing blocking the page.
* Own database tables with proper indexes; dashboard statistics are cached.
* The public tracking endpoint is hardened: rate limiting, event allowlist, batch and payload size caps, strict validation.

Built by [Dreamfox](https://dreamfoxmedia.com).

== Installation ==

1. Upload the plugin files to `/wp-content/plugins/dreamfox-form-analytics`, or install through the WordPress plugins screen.
2. Activate the plugin through the 'Plugins' screen.
3. Visit a page containing a Contact Form 7 or Elementor form — tracking starts immediately.
4. Open **Dreamfox Analytics** in the admin menu to watch the funnel fill up.
5. Review **Dreamfox Analytics → Settings** for retention, Do Not Track and exclusion options.

== Frequently Asked Questions ==

= Does this plugin store what visitors type into my forms? =

No, never. The tracker only records *that* a field was focused, completed or produced a validation error — identified by the field's technical name — plus timing. Field contents never leave the browser, and the server-side validator actively strips anything that looks like content before storing events.

= Is it GDPR-friendly? Do I need a cookie banner for it? =

The plugin uses no cookies and no persistent identifiers, stores no personal data, and respects Do Not Track / Global Privacy Control out of the box. Suggested privacy-policy text is provided under Settings → Privacy in WordPress. Whether a consent banner is required for your site remains your decision — but this plugin was built to make anonymous analytics possible.

= Which form plugins are supported? =

Contact Form 7 and Elementor Forms (Elementor Pro) in this version. The plugin detects them automatically and causes no errors when they are absent. More integrations are planned.

= How is "abandoned" defined? =

A visitor started interacting with the form (focused or filled a field) but left the page without a successful submission. The last field they touched gets the drop-off attribution — that's how the per-field drop-off table is built.

= What is the difference between form_submit and a successful submission? =

A submit attempt that fails validation is not a successful submission. Completion and conversion rates count confirmed successes only (e.g. Contact Form 7's "mail sent" event).

= Does it slow down my site? =

The tracker is a single small vanilla-JS file, loaded only when needed. Events are batched (at most one request per ~5 seconds per page) and sent with `sendBeacon` on page exit so nothing blocks navigation.

= Can I delete all data when removing the plugin? =

Yes. Enable *"Delete all analytics data when the plugin is uninstalled"* under Settings → Privacy, then delete the plugin. Without that opt-in, deactivating or deleting keeps your data for a later reinstall.

= Who can see the analytics? =

Users with the `dffa_view_analytics` capability (administrators by default). Settings require `dffa_manage_settings`. Both capabilities can be granted to other roles with any role editor.

== Screenshots ==

1. Dashboard: funnel cards, trend and problem fields at a glance.
2. Forms overview with per-form completion and abandonment rates.
3. Form detail: funnel, per-field drop-off and notable-field insights.
4. Settings: tracking, privacy and exclusion options.

== Changelog ==

= 1.0.1 =
* Fixed a bug where per-field drop-off attribution and the "orphaned event" cleanup step could fail on hosts running the WordPress SQLite Database Integration drop-in instead of MySQL/MariaDB, due to MySQL-only SQL syntax.
* Hardened all database queries against a WordPress.org Plugin Check security finding (table names are now passed through `%i` identifier placeholders instead of being interpolated into the SQL string) — no functional change, all values were already hardcoded constants.

= 1.0.0 =
* Initial release.
* Funnel tracking (views, starts, field progression, validation errors, abandonment, submissions) for Contact Form 7 and Elementor Forms.
* Privacy-first tracker: cookieless, anonymous, DNT/GPC-aware, no field values ever stored.
* Admin dashboard with trend charts, forms overview, form detail with per-field statistics and deterministic "notable fields" insights.
* Configurable retention (7–365 days) with daily cleanup, WordPress privacy-tools integration, hardened REST tracking endpoint.

== Upgrade Notice ==

= 1.0.0 =
Initial release.
