=== MetricPanel Analytics ===
Contributors: fiftyone
Tags: analytics, privacy, cookieless, consent, metricpanel
Requires at least: 6.3
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 1.0.1
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Connect WordPress to privacy-aware MetricPanel analytics without editing your theme.

== Description ==

MetricPanel Analytics connects your WordPress site to MetricPanel without theme edits or copied
script tags. Save your Website ID once and the plugin adds the deferred tracker to public pages
through WordPress's script APIs.

= What you can measure =

* Automatic pageviews across your public WordPress site.
* Visitors and sessions without tracking WordPress admin screens.
* Referrers and UTM campaign parameters for acquisition reporting.
* Device, browser, operating system, and screen details sent by the tracker.
* Optional geolocation enrichment when it is appropriate for your site.

= Built for WordPress =

* No-code setup under Settings > MetricPanel.
* Deferred footer loading through the standard WordPress script API.
* A single registered tracker handle to avoid duplicate injection by this plugin.
* Support for the hosted MetricPanel API, a first-party proxy, or a custom deployment.
* An admin-only configuration test plus authenticated dashboard verification.
* Clean uninstall of the settings stored by the plugin.

= Privacy controls =

* Cookieless mode keeps identifiers in sessionStorage or memory for the browser session.
* Consent mode waits for your consent manager before analytics events are sent.
* Geolocation can be disabled independently.
* Suggested disclosure text is added to WordPress's Privacy Policy Guide.

These controls help you configure MetricPanel for your site, but they do not guarantee compliance.
Your site owner remains responsible for notices, consent, and other legal requirements.

= How it works =

1. Create a website in your [MetricPanel dashboard](https://metricpanel.io).
2. Copy its Website ID.
3. Install and activate MetricPanel Analytics in WordPress.
4. Open Settings > MetricPanel, paste the Website ID, and choose your privacy settings.
5. Visit the public site and verify the installation from MetricPanel.

= Current scope =

Version 1.0.1 tracks website analytics only. WooCommerce revenue tracking is not included, and the
plugin does not infer purchases from pageviews. WooCommerce revenue attribution remains a separate
integration phase.

The plugin does not expose a public health endpoint. Its configuration test requires an
administrator capability and a WordPress nonce. MetricPanel dashboard verification is also
authenticated and reports plugin configuration separately from observed traffic.

== External services ==

MetricPanel Analytics is a client for the hosted MetricPanel analytics service. The service is
required for the plugin to provide analytics. Activating the plugin alone does not contact
MetricPanel; the public tracker is loaded after an administrator saves a Website ID.

When configured, public pages load the tracker from https://app.metricpanel.io. The tracker sends
analytics events to https://api.metricpanel.io or to the administrator-configured first-party proxy.
Event data can include the MetricPanel Website ID, generated visitor and session identifiers, URL
path and query parameters, page title, referrer, campaign parameters, device category, screen
dimensions, browser, operating system, timestamp, privacy-mode flags, and custom event data added by
the site. Network requests also disclose the visitor's IP address and user agent to the receiving
service. IP addresses may be used for geolocation unless the administrator enables Disable
geolocation.

By default, the tracker stores generated visitor and session identifiers in first-party cookies.
Cookieless mode uses sessionStorage or in-memory identifiers for the current browser session. Wait
for consent mode downloads the tracker but does not send analytics events until the site's consent
manager calls window.metricpanel.giveConsent(). The site owner is responsible for choosing the
appropriate settings, providing any required notice, and obtaining any required consent.

The admin-only configuration health check requests the configured tracker URL from the WordPress
server when an administrator clicks Test configuration.

* [MetricPanel website and dashboard](https://metricpanel.io)
* [MetricPanel tracker service](https://app.metricpanel.io)
* [MetricPanel analytics API](https://api.metricpanel.io)

= Legal documents =

* [MetricPanel Privacy Policy](https://metricpanel.io/privacy)
* [MetricPanel Terms of Service](https://metricpanel.io/terms)

= Support =

For setup help and troubleshooting, read the
[MetricPanel installation guide](https://metricpanel.io/docs/install-guides).

== Privacy ==

MetricPanel provides cookieless, consent-gated, and geolocation-disabled modes, but no plugin can
guarantee legal compliance. Review the External services section and update your site's privacy and
cookie notices to match the settings you enable. WordPress also adds suggested MetricPanel text to
Settings > Privacy > Policy Guide after activation.

== Installation ==

1. In WordPress, open Plugins > Add New Plugin.
2. Search for MetricPanel Analytics.
3. Install the plugin by contributor fiftyone, then activate it.
4. Open Settings > MetricPanel.
5. Paste the Website ID shown in MetricPanel onboarding.
6. Confirm the tracker URL and API or first-party proxy URL.
7. Choose the privacy, consent, localhost, and debug settings appropriate for the site.
8. Save settings, visit the public site, then use Verify WordPress installation in MetricPanel.

Do not install the tracker through both this plugin and a theme, tag manager, or header-injection
plugin. MetricPanel's tracker has a browser duplicate guard, but only one installation should be
maintained.

== Frequently Asked Questions ==

= Do I need a MetricPanel account? =

Yes. Create a MetricPanel website first, then copy its Website ID into Settings > MetricPanel.

= When does tracking start? =

The tracker is added to public pages after an administrator saves a valid Website ID. Activating
the plugin by itself does not load the tracker or contact MetricPanel.

= How does consent mode work? =

Choose Wait for consent manager to add MetricPanel's consent flag. Your consent manager must call
window.metricpanel.giveConsent() after analytics consent is granted.

= Can I use MetricPanel without persistent cookies? =

Yes. Enable Cookieless tracking to keep generated visitor and session identifiers in
sessionStorage or memory for the current browser session instead of persistent cookies.

= Will the plugin slow down my website? =

The plugin loads the tracker with defer in the footer, so it does not block HTML parsing. Every
analytics script still uses network and browser resources, so measure the result on your own theme,
hosting, and plugin stack.

= Does the plugin track WooCommerce revenue? =

No. Version 1.0.1 installs the website analytics tracker only. WooCommerce order and revenue
tracking require a separately implemented and tested integration.

= Can I use a first-party proxy or custom MetricPanel deployment? =

Yes. Advanced settings let an administrator replace the tracker and API URLs. Production endpoints
must use HTTPS; local HTTP is permitted only when localhost tracking and debug mode are both enabled.

= Where is analytics data sent? =

The configured tracker sends events to the hosted MetricPanel API or the first-party proxy selected
by the administrator. See External services above for the data categories and default endpoints.

= How do I disconnect MetricPanel? =

Clear the Website ID or deactivate the plugin to stop loading the tracker. Uninstalling the plugin
removes its WordPress settings but does not delete your MetricPanel account or previously collected
analytics data.

== Changelog ==

= 1.0.1 =

* Reworked the WordPress.org description with clearer features, setup, privacy, and performance details.
* Expanded the FAQ and clarified the current WooCommerce revenue boundary.

= 1.0.0 =

* Initial WordPress.org release.
* Added secured settings and configuration health check.
* Added privacy, consent, localhost, and debug controls.
