=== Dreamfoxmedia Form Analytics ===
Contributors: dreamfox
Tags: form analytics, form abandonment, contact form 7, elementor forms, conversion tracking
Requires at least: 6.5
Tested up to: 7.1
Requires PHP: 8.1
Stable tag: 1.0.4
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).

= How is this different from Google Analytics or Google Tag Manager? =

Generic analytics tools show page views and events, but you have to set up form tracking yourself and they usually need cookies and consent. This plugin is built for forms only: it detects Contact Form 7 and Elementor forms automatically and shows the funnel, per-field drop-off and validation errors with no configuration, no cookies and no personal data.

= Will it work with WPForms, Gravity Forms or Fluent Forms? =

Not yet. This version supports Contact Form 7 and Elementor Forms (Elementor Pro). The integration layer is prepared for more form plugins in future releases.

= 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.4 =
* Renamed to Dreamfoxmedia Form Analytics.

= 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.4 =
Renamed to Dreamfoxmedia Form Analytics. No functional changes.

= 1.0.0 =
Initial release.
