=== MetricPoints Browser Beacon ===
Contributors: mjloeff
Tags: event tracking, javascript events, performance monitoring, csp monitoring, security headers
Requires at least: 5.8
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.3.8
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Find broken client sites before they cost you the account. Optional WordPress evidence for MetricPoints.

== Description ==

MetricPoints Browser Beacon connects a WordPress site to a MetricPoints account. Browser collection stays off until you enable the beacon and choose a consent mode. You can also send WordPress health snapshots, suggest a Content Security Policy report URI, or have this plugin write CSP headers.

Michael Loeffler develops this plugin at Main Street Web Developer for MetricPoints.

= What it sends =

* JavaScript errors, unhandled promise rejections, and runtime exceptions, when the beacon is enabled and the consent setting allows it
* Core Web Vitals and memory use, when performance collection is enabled
* Session data only if you turn that on. Fingerprinting and persistent browser storage stay off
* CSP reports, or a report-only or enforcing CSP header if you choose that mode
* WordPress health snapshots: versions, cron, forms, mail attempts, cache, and WooCommerce signals

Snapshots do not include submitted form fields, email bodies, recipients, passwords, or the private connector credential.

= Where the credentials come from =

MetricPoints creates both values. Open the client site, choose Setup, and use the WordPress plugin card. Copy the site key, choose Create credential, and copy that value once. Paste each one into its own field on WordPress → Settings → MetricPoints, then save and verify.

== Installation ==

1. Upload the plugin files to the `/wp-content/plugins/metricpoints-browser-beacon` directory, or install the plugin through the WordPress plugins screen directly.
2. Activate the plugin through the Plugins screen in WordPress.
3. In MetricPoints, open the site and choose Setup. Copy the site key from the WordPress plugin card. Choose Create credential and copy that value immediately.
4. In WordPress, go to Settings → MetricPoints.
5. Paste the site key and private connector credential into their separate fields.
6. Save settings, then verify the connection. Enable the browser beacon only after choosing the collection and consent settings for this site.

== External Service ==

This plugin connects to the MetricPoints service at https://metricpoints.com. Saving a public site key sends a verification request, initially to https://metricpoints.com and subsequently to the selected API host. With a private connector credential configured, WordPress also sends signed verification requests, scheduled health snapshots, and results of approved actions. The service can assign https://ingest.metricpoints.com for these requests; the plugin can fall back to https://metricpoints.com if that host is unavailable. Browser report endpoints follow the selected API host, while the browser script loads from https://ingest.metricpoints.com. Snapshots contain the site's URLs, software and configuration signals, operational counts, status codes, and finding summaries. They do not contain submitted form fields, email bodies, recipients, passwords, or the private credential. If the browser beacon is separately enabled and the chosen consent gate permits it, visitors load a script from that intake host and can send browser errors, performance data, and any separately enabled interaction data. If CSP reporting is configured, browsers send CSP violation reports to the selected API host. When an administrator clicks Check API access, WordPress sends credential-free connectivity requests to both hosts, even before a site key is entered. These requests expose normal connection metadata, including the server IP address, but do not send the site key or private connector credential.

For an explicitly enabled staging test-order check, MetricPoints sends the new WooCommerce order key back to this site's signed proof endpoint. The plugin returns only whether WooCommerce recorded and marked that order paid, its status, and creation time. The order key and customer details are not included in the saved result.

MetricPoints terms: https://metricpoints.com/terms
MetricPoints privacy policy: https://metricpoints.com/privacy

= Optional remote actions =

Remote actions are off by default. An administrator must enable safe remediation in the plugin settings, and each request requires explicit approval in MetricPoints and a signed request authenticated with this site's private connector credential. Supported actions can send a health snapshot, run a connector self-check, clear supported page or object caches, refresh permalink rewrite rules, trigger WordPress cron or a bounded Action Scheduler run, or send a diagnostic email to the site's configured administrator email address. Cron and queue runs execute due work registered by WordPress and other plugins. Diagnostic email checks mail handoff, not inbox delivery. Action status and bounded operational evidence are returned to MetricPoints; the email recipient and message body are not included in that result.

== Frequently Asked Questions ==

= Do I need a MetricPoints account? =

Yes. This plugin requires a MetricPoints account and access to the relevant service features. The plugin itself is free; service features may require a paid plan. See https://metricpoints.com/pricing and the service terms for current plans, limits, and any trial conditions.

= What data is collected? =

When enabled, the browser beacon can send JavaScript errors, performance and network signals, and optional user interaction data. User tracking, session replay, and network monitoring are off by default. The WordPress connector sends bounded operational counts, timestamps, status codes, and selected configuration signals; it does not send form field values, email contents, or private connector credentials. See the plugin settings and privacy documentation before enabling collection.

= How do consent and privacy controls work? =

The site operator is responsible for choosing a legal basis, configuring notices and retention, and obtaining consent where required. By default the beacon waits for the `metricpoints_browser_beacon_consent_granted` WordPress filter to return true for a visitor. An operator can explicitly select collection without this gate after their own privacy review. Fingerprinting and persistent browser storage remain disabled.

The settings page shows the saved consent choice but cannot verify consent for an individual visitor. Check a public page before and after granting consent. Session replay also requires user tracking and the browser beacon to be enabled. A successful admin test event confirms delivery to MetricPoints; it does not prove that visitor collection or consent gating works on public pages.

= Does this affect site performance? =

WordPress loads the browser script in the page footer when enabled and permitted by the consent setting, then initializes it in order. It still adds a network request and processing work; measure its impact on your site.

= Can I track events in the WordPress admin? =

Yes, you can enable admin tracking in the plugin settings.

= Does the plugin have to manage my CSP? =

No. CSP has an external-owner mode where WordPress does not write CSP headers. Use that when CSP is already managed by your host, CDN, server config, or another security plugin.

= What is the safest CSP mode? =

Start with external-owner mode or report-only mode. Only use enforcing mode after your policy has been tested.

== Changelog ==

= 1.3.8 =
* Harden quiet-test mail guards, submission interception and cleanup ownership; retain changed or legacy unverified entries for review.

= 1.3.7 =
* Add provider-bound quiet tests for WPForms, Formidable, Fluent Forms and Contact Form 7, with explicit cleanup capabilities and no-storage receipts.

= 1.3.6 =
* Send authenticated, retryable cleanup receipts so MetricPoints can confirm test-entry removal.
* Treat a missing WordPress hook as unsupported during quiet-test preflight instead of failing the request.

= 1.3.5 =
* Add opt-in authenticated Gravity Forms quiet tests, safe notification redirection, and bounded automatic test-entry cleanup.

= 1.3.4 =
* Load settings and browser scripts through the WordPress enqueue APIs and keep settings helpers privately scoped.
* Preserve browser consent gating and initialize the hosted beacon after its footer script loads.
* Clarify service hosts, credential-free connectivity checks, account requirements, and optional approved remote actions.

= 1.3.3 =
* Add an administrator-only, credential-free API access check for the ingest and main hosts, with DNS, TLS, timeout, and unexpected-response guidance.
* Show the currently selected API hostname separately from connectivity results.

= 1.3.2 =
* Verify the site key against metricpoints.com when the dedicated intake host cannot be reached, instead of reporting that failure as an invalid API key.
* Show the MetricPoints site domain separately from this WordPress address. The domain comes from the connected MetricPoints site and refreshes after a successful verification.
* Explain that the private connector credential is created in MetricPoints at the site Setup tab, and pasted on WordPress → Settings → MetricPoints.
* Show when the saved private credential last connected successfully. The password field stays blank so the credential is never displayed again.

= 1.3.1 =
* Reorganize the connector settings into connection, browser collection, and WordPress evidence sections with a compact status summary.
* Show consent-gated browser collection and WordPress snapshot status separately.

= 1.3.0 =
* Add a signed, read-only WooCommerce order-proof response for explicitly enabled staging test orders. It returns bounded order status and payment confirmation without customer details or the order key.

= 1.2.0 =
* Separate the public browser key from an encrypted, site-specific private connector credential used for signed WordPress evidence and approved actions.
* Reject replayed, stale, or wrong-site snapshots; reserve action idempotency keys before execution.
* Default user and network tracking off, disable fingerprinting and persistent browser storage, and require an explicit collection and consent choice.
* Use the dedicated MetricPoints intake host for new connections.

= 1.1.8 =
* Follow the report intake address MetricPoints assigns on verification and check-in. Only trusted HTTPS MetricPoints intake hosts are accepted.
* Pass error and performance endpoints to the browser beacon and build the CSP report-uri from the same address.
* Add the METRICPOINTS_API_BASE_URL constant and the metricpoints_browser_beacon_api_base_url filter for self-managed overrides.
* Allow https://*.metricpoints.com in the suggested connect-src.

= 1.1.7 =
* Flag cached WooCommerce cart, checkout, or account pages and checkout scripts stripped by optimization plugins.
* Record fatal fingerprints after updates (relative path, plugin slug, hashed message) without URI, POST, or debug.log.
* Attach version-from/to and automatic versus manual on update events. Failed updates are findings; successful updates stay correlation context.
* Classify wp_mail by family and notice WooCommerce orders with no WooCommerce mail attempts. Inbox delivery is not claimed.
* Treat production maintenance and coming-soon as coverage so form and order silence is not scored as a broken funnel.

= 1.1.6 =
* Report WooCommerce store functioning: coming-soon and catalog visibility, a no-order add-to-cart or Store API probe, failed-versus-completed order ratios, gateway public-field presence without secrets, and shipping-method counts for the store country.

= 1.1.5 =
* Close Contact Form 7, Ninja Forms, Elementor Forms, and Happyforms submission storage. CF7 uses Flamingo, CFDB7, or Advanced CF7 DB when present. Missing storage emits form_health.storage_unavailable coverage, not a site failure.

= 1.1.4 =
* Record privacy-safe form submission success, failure, and same-request WordPress mail failures for Gravity Forms, WPForms, Fluent Forms, Formidable, and Contact Form 7. Emits form_health.recent_submission_failures and form_health.mail_failed_after_submission. Field values are not collected.

= 1.1.3 =
* Report form-submission silence when a previously active form stores no entries after a two-week baseline. Suppression applies on maintenance, coming-soon, non-production, and low-volume forms. No field values are collected.

= 1.1.2 =
* Make MetricPoints the source of environment truth. Use plugin setting only as the default/fallback.

= 1.1.1 =
* Fixed test-event generation when the hosted browser beacon is still loading or blocked in wp-admin.
* Synced the displayed plugin environment from the connected MetricPoints site after verification and made it read-only once connected.
* Fixed shared browser/CSP API keys so the main WordPress connector key verifies as browser/event tracking.
* Removed CORS-triggering script attributes from the WordPress connector loader.

= 1.1.0 =
* Added privacy-safe WordPress health snapshots for application context, search visibility, form health, mail dispatch, change events, cron, cache, WooCommerce, and runtime compatibility.
* Added signed, explicit-approval action support for low-risk connector actions.
* Added explicit connector self-check and controlled mail diagnostic actions for test-site validation.
* Added action result reporting so MetricPoints can record completed, failed, and rejected WordPress connector actions as operational evidence.

= 1.0.0 =
* Initial release
* JavaScript event tracking
* Performance monitoring (Core Web Vitals)
* User session tracking
* Optional CSP monitoring and WordPress-managed CSP modes
* Admin configuration panel
* Real-time event reporting
* Configurable privacy controls

== Upgrade Notice ==

= 1.3.4 =
Uses WordPress-managed footer scripts and clarifies external-service disclosures. Existing settings and credentials are preserved.

= 1.3.3 =
Adds a credential-free API access check for both hosts. Existing endpoints and fallback behavior are unchanged.

= 1.3.2 =
Site key verification follows the MetricPoints host that is actually accepting connections. Re-save or verify the connection after updating.

= 1.3.1 =
The settings screen has been reorganized. Existing credentials and collection choices are preserved.

= 1.3.0 =
Install this release on connected staging WooCommerce sites before enabling MetricPoints paid test-order checks. Keep the store payment gateway in sandbox mode.

= 1.2.0 =
After upgrading, create and enter a private WordPress connector credential in Site Health. WordPress evidence and actions require it. Rotate any browser keys previously exposed under the older shared-key design after connected sites are upgraded.

= 1.1.0 =
Adds connected-site health evidence and explicit-approval connector actions for MetricPoints assurance testing.

= 1.0.0 =
Initial release of MetricPoints Browser Beacon. Install and configure your API key to start tracking browser health.

== Support ==

For support, visit https://metricpoints.com or email hello@metricpoints.com.

This plugin is developed by Michael Loeffler at Main Street Web Developer: https://mainstreetwebdeveloper.com

== Credits ==

Developed by Michael Loeffler at Main Street Web Developer (https://mainstreetwebdeveloper.com) for MetricPoints.
