=== MetricPoints Browser Beacon ===
Contributors: michaelloeffler
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.1
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Install the MetricPoints browser beacon on WordPress and optionally connect CSP monitoring without editing your theme.

== Description ==

MetricPoints Browser Beacon connects optional WordPress health evidence and browser telemetry to a MetricPoints site. Browser collection is off until the site operator enables the beacon and selects a consent mode. The connector can also suggest a Content Security Policy reporting URI or write CSP headers when explicitly configured.

**Key Features:**

* **JavaScript Event Tracking** - Captures unhandled browser events, promise rejections, and runtime exceptions when enabled and permitted by the consent setting
* **Performance Monitoring** - Tracks Core Web Vitals and memory usage when enabled and permitted
* **Optional User Session Tracking** - Off by default; fingerprinting and persistent browser storage are disabled
* **Reporting** - Sends permitted events to the MetricPoints dashboard
* **Optional CSP Monitoring** - Keep CSP managed externally, write report-only headers, or opt into WordPress-managed CSP
* **Admin Configuration** - Easy-to-use WordPress admin interface
* **Privacy-Friendly** - Configurable tracking options with privacy controls
* **Environment Support** - Tag events by environment (production, staging, development)

**Perfect For:**

* WordPress site owners who want to monitor JavaScript events
* Developers debugging frontend issues
* Site administrators tracking performance metrics
* Teams managing multiple WordPress sites
* Site owners who want CSP visibility without editing theme files

== External Service ==

This plugin connects to the MetricPoints service at https://metricpoints.com. After an operator enters the public site key and private connector credential, WordPress sends verification requests, scheduled health snapshots, and results of approved actions to 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 same intake host.

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

== 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. Go to Settings → MetricPoints.
4. Copy the public site API key and private WordPress connector credential from MetricPoints Site Health into their separate fields.
5. Choose browser collection and consent settings, then save and verify. WordPress evidence and approved actions require the private credential.

== Frequently Asked Questions ==

= Do I need a MetricPoints account? =

Yes, you need a free MetricPoints account to use this plugin. Sign up at https://metricpoints.com.

= 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.

= Does this affect site performance? =

The browser script loads asynchronously when enabled and permitted by the consent setting. 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.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.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

== Credits ==

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