=== Formhawk ===
Contributors: al5dy
Tags: forms, form analytics, conversion, form tracking, privacy
Requires at least: 6.4
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 0.1.1
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Privacy-first form conversion analytics and health monitoring for Contact Form 7 and standard HTML forms.

== Description ==

Formhawk is a privacy-first form conversion analytics and health monitoring plugin for WordPress.

It helps answer two practical questions:

* Are my forms working?
* Where do visitors abandon them before submitting?

Formhawk automatically discovers eligible frontend forms, measures conversion and friction, monitors form health, and stores analytics locally in WordPress as aggregate statistics.

No external Formhawk account or cloud analytics service is required.

= Current features =

* Automatic detection of Contact Form 7 forms.
* Automatic detection of standard HTML `<form>` elements.
* Detection of forms inserted dynamically after page load, including AJAX and popup forms.
* Form view tracking when a form enters the viewport.
* Form start tracking on first interaction.
* Field interaction tracking without reading field values.
* Observed form submission tracking.
* Server-confirmed Contact Form 7 success tracking.
* Contact Form 7 mail failure tracking through server-side hooks.
* Contact Form 7 validation failures by field.
* Contact Form 7 aborted submission failures.
* Form abandonment tracking for started forms left without completion.
* Last interacted field before abandonment.
* Validation error counts by field.
* Views, starts, submissions, abandonments and failures.
* Conversion and abandonment rates.
* Average time from form start to a terminal event.
* Last confirmed success and last failure timestamps.
* Per-form health states: Collecting, Healthy, Warning and Critical.
* Warnings for started forms with no submissions and viewed forms with no starts.
* Critical state when a newer failure exists after the last confirmed success.
* Conversion-drop detection against the previous comparable period.
* 7-day, 30-day and 90-day analytics views.
* Forms overview dashboard and detailed per-form analytics.
* Field-level abandonment and validation friction reports.
* Global WordPress `wp_mail()` success/failure health signals.
* Manual `wp_mail()` diagnostic test.
* Local daily aggregate analytics storage with no raw visitor event log.
* Automatic daily retention cleanup.
* Configurable retention: 30, 90, 180 or 365 days.
* Optional complete data removal on uninstall.
* WordPress Privacy Policy helper text integration.
* No cookies, `localStorage` or `sessionStorage` tracking.
* No visitor IDs, session IDs, IP addresses or user-agent storage.
* No form field values, entered email addresses, names or message contents stored.
* No email recipient, subject or message body storage.
* Same-origin REST event ingestion with a signed site token.
* Batched frontend event delivery.
* Dependency-free frontend tracker.
* `MutationObserver` support for dynamically inserted forms.
* `IntersectionObserver` support for actual form-view detection.
* `data-formhawk-ignore` to exclude individual forms.
* `data-formhawk-title` and `data-formhawk-id` for generic form identification.
* `formhawk_tracking_disabled` filter to disable tracking programmatically.
* `formhawk_event_recorded` action for integrations and extensions.

= Privacy by design =

Formhawk is intentionally built without visitor-level analytics.

Temporary per-form state exists only in JavaScript memory for the current page. Formhawk creates no analytics cookies or persistent browser identifiers.

The local WordPress database stores aggregate counts and static metadata needed for reports, such as form identifiers, page paths, field names and field labels.

Formhawk does not intentionally store visitor responses, names, email addresses, phone numbers, message contents, IP addresses, visitor IDs, session IDs, user agents, email recipients, email subjects or email message bodies.

No Formhawk analytics data is sent to an external Formhawk service.

= Contact Form 7 integration =

Contact Form 7 receives the deepest integration in the current release. Formhawk combines frontend behavior analytics with server-side Contact Form 7 hooks for confirmed mail success, mail failures, validation failures and aborted submissions.

= Standard HTML forms =

Formhawk automatically monitors eligible standard HTML forms. For generic forms, the browser submit event is recorded as an observed submission attempt.

There is no universal browser API that can verify whether every custom server-side handler ultimately saved or delivered a lead, so Formhawk does not claim a confirmed success where it cannot verify one.

= Mail health =

Formhawk monitors WordPress `wp_mail_failed` and `wp_mail_succeeded` events without storing message contents or recipients.

A successful `wp_mail()` event means WordPress/PHPMailer accepted the message for sending without an immediate error. It does not guarantee final inbox delivery.

== Installation ==

1. Upload the `formhawk` folder to `/wp-content/plugins/`, or install the ZIP through Plugins > Add New Plugin > Upload Plugin.
2. Activate Formhawk.
3. Open Formhawk in the WordPress admin menu.
4. Visit a frontend page containing a Contact Form 7 or standard HTML form.
5. Once the form enters the viewport, Formhawk starts collecting aggregate analytics automatically.
6. Return to Formhawk in wp-admin to review conversion, abandonment, friction and health information.

No tracking snippet, external account or cookie configuration is required.

== Frequently Asked Questions ==

= Does Formhawk store submitted form values? =

No. The frontend tracker does not read or transmit visitor field values. Only static field metadata, such as names or labels, is used for aggregate friction reports.

= Does Formhawk use cookies or browser storage? =

No. Formhawk creates no analytics cookies, localStorage entries or sessionStorage entries.

= Does Formhawk send analytics to an external service? =

No. Current Formhawk analytics are stored locally in the WordPress database.

= Which forms are supported? =

The current release supports Contact Form 7 and eligible standard HTML forms, including forms inserted dynamically after page load.

= Can Formhawk confirm every submission? =

Contact Form 7 outcomes are confirmed through server-side hooks. Generic HTML forms are recorded as observed browser submission attempts because arbitrary server-side handlers cannot be verified universally.

= Does wp_mail_succeeded mean the email reached the inbox? =

No. It means WordPress/PHPMailer completed the send operation without an immediate error. Final delivery can still fail later.

= How do I exclude a form? =

Add `data-formhawk-ignore` to the `<form>` element.

`<form data-formhawk-ignore>`

= How do I give a generic form a better name? =

Use `data-formhawk-title` and optionally `data-formhawk-id`.

`<form data-formhawk-title="Request a Quote" data-formhawk-id="request-quote">`

= Can developers disable tracking programmatically? =

Yes. Return `true` from the `formhawk_tracking_disabled` filter.

= Is there an extension hook after an event is recorded? =

Yes. The `formhawk_event_recorded` action fires after an aggregate event is recorded.

= How long is analytics data retained? =

Choose 30, 90, 180 or 365 days in Formhawk settings. Expired daily aggregate data is cleaned automatically.

= What happens when Formhawk is uninstalled? =

Analytics can be preserved by default. Enable the uninstall cleanup setting if you want Formhawk data removed when the plugin is deleted.

== Screenshots ==

1. Forms overview with conversion and health status.
2. Detailed per-form conversion and health analytics.
3. Field-level abandonment and validation friction reporting.
4. WordPress mail health diagnostics and manual mail test.
5. Retention and uninstall data settings.

== Changelog ==

= 0.1.1 =
* Hardened SQL preparation for aggregate counter upserts.
* Updated WordPress compatibility metadata for WordPress 7.1.
* Resolved Plugin Check release-blocking issues.

= 0.1.0 =
* Initial public MVP release.
* Added Contact Form 7 and standard HTML form discovery.
* Added views, starts, interactions, submissions and abandonment analytics.
* Added field-level abandonment and validation reporting.
* Added conversion, abandonment and timing metrics.
* Added server-side Contact Form 7 success, failure and validation monitoring.
* Added WordPress mail health monitoring and diagnostics.
* Added health states and conversion-drop detection.
* Added local aggregate storage, retention cleanup and privacy controls.
* Added dynamic form discovery and developer extension hooks.

== Upgrade Notice ==

= 0.1.1 =
Plugin Check hardening and WordPress 7.1 compatibility metadata.

= 0.1.0 =
Initial public release of Formhawk.
