=== WebDig.DEV Analytics ===
Contributors: webdigpt
Tags: analytics, umami, dashboard, woocommerce, core-web-vitals
Requires at least: 6.4
Tested up to: 7.1
Requires PHP: 8.0
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Self-hosted Umami analytics, visitor insights, Core Web Vitals and WooCommerce events in your WordPress dashboard.

== Description ==
Connect WordPress to your own HTTPS Umami server. A dashboard widget displays hourly visits for the last 24 hours, visitor estimates, page views, average visit duration and bounce rate.

Browse pages, browsers, languages, operating systems, devices and visitor countries. A configurable share URL opens the full Umami report in a new tab.

Features:
* Automatic page views and configurable link/button/contact/download events.
* Optional scroll milestones and form submission attempts; successful Contact Form 7 submissions.
* Official Umami real-user performance collection: LCP, INP, CLS, FCP and TTFB.
* WooCommerce product, cart, checkout and paid order confirmation events; HPOS compatibility.
* Server-side report requests, encrypted API keys, capability and nonce checks.
* English source strings with bundled Portuguese (Portugal) translations for PHP and JavaScript.
* No analytics data or credentials are sent to WebDig. Data goes to the Umami server you configure.

Requirements: a self-hosted Umami server version 3.2 or later; HTTPS connectivity from WordPress and visitor browsers. Dashboard access needs an API key or a valid Bearer token. Use a separate Umami account that can only access the relevant website.

= External service and privacy =
The plugin loads the official tracker from your configured server's /script.js endpoint. The tracker sends page views, event data, browser/device information and, when enabled, performance measurements to that server. It uses the visitor IP for Umami processing and geographic estimates. Refer to your Umami server's privacy policy and configuration. Umami documentation: https://docs.umami.is/docs/ . No central WebDig analytics service is required.

Automatic tracking excludes form values, customer names, customer emails and addresses. URLs exclude query strings and fragments, including order keys; this also excludes UTM attribution from URLs. User-supplied custom event data remains the site owner's responsibility.

Purchase deduplication stores an order marker in the visitor's localStorage. The plugin does not integrate a consent banner or wait for consent. Its analytics settings do not determine your website's legal obligations.

= Purchase tracking scope =
Purchases are tracked in the browser when the order is paid and the customer returns to a valid order confirmation URL. The order key is verified and is not sent to Umami. Delayed bank-transfer/Multibanco payments are not tracked through a payment webhook. Reloads are deduplicated in the same browser, but cross-device or cleared-storage duplicates remain possible. Refunds do not amend the original Umami event. Analytics revenue is not an accounting record.

Legacy AJAX cart events and WooCommerce Blocks events are supported. Non-AJAX product form submissions are recorded as add_to_cart_attempt, not confirmed cart additions. Custom cart extensions can require their own integration.

Portuguese (Portugal) documentation is included in readme-pt_PT.txt. / A documentação em português de Portugal está incluída em readme-pt_PT.txt.

== Installation ==
1. Upload the ZIP in Plugins > Add New > Upload Plugin and activate it.
2. Create a website in your Umami instance and copy its Website ID.
3. Open WebDig.DEV Analytics in the WordPress admin menu.
4. Enter your server base URL, Website ID and report API key. Enable tracking.
5. Optionally enter the Umami share URL and select the tracking features you need.
6. Remove other Umami snippets/plugins and clear site/CDN caches.
7. Open Dashboard > Home to view the statistics widget. If hidden, enable it in Screen Options.
8. Test tracking in a private browser window. Administrators are excluded from tracking by default.

Plugin activation, tracking and widget visibility are separate. Activate the plugin on the Plugins page, then enable tracking in its settings to start collecting visits. Showing or hiding the dashboard widget does not start or stop tracking. Statistics are displayed in the WordPress administration area and Umami, not on public site pages. The API key is required for dashboard reports, but not for collecting visits.

Settings remain when deactivating or updating the plugin. Uninstalling deletes this site's plugin settings and local report caches. It does not delete data on your Umami server. Multisite installs must be configured separately per site; network-wide provisioning is not included.

== Frequently Asked Questions ==

= Visitors versus visits? =
Visitors are anonymous unique visitor estimates. Visits count browsing sessions. One visitor can generate multiple visits. Neither is an exact count of people.

= Where are Core Web Vitals displayed? =
Enable the performance option and open your website's Performance section in Umami. New data is collected from real visitor browsers; no historical measurements are generated.

= Can I change a saved API key? =
Delete the key first, then save a new one. Keys defined as WEBDIG_ANALYTICS_API_TOKEN in wp-config.php must be changed there. Changing WordPress salts invalidates keys stored encrypted in the database.

= How do languages work? =
The admin interface follows the user's WordPress language. English is the source language. Portuguese (Portugal), locale pt_PT, is included. The languages directory contains a POT template, PO/MO translations and WordPress JavaScript JSON catalogs. Third-party data, custom event names and browser names are not translated by gettext.

= Can I hide the dashboard panel? =
Yes. Use Screen Options on the WordPress dashboard. The widget is available by default to administrators and, when enabled, shop managers. Other roles do not gain access to analytics data.

= Do I need a separate pixel? =
No. The plugin loads the configured Umami tracker. The reporting API key stays on the WordPress server.

== Changelog ==

= 1.0.0 =
* Updated plugin name to WebDig.DEV Analytics, author to WebDig and author website to https://webdig.dev.
* Updated bundled translations and added Portuguese documentation.

* Stable release with English source strings and complete Portuguese (Portugal) UI translations.
* Visitor countries replace screen resolutions; country codes are displayed as localized names.
* Clear visitor/visit definitions and generic server setup instructions.
* Dashboard assets load at the WordPress admin enqueue stage.
* Input validation hardening and documented privacy/purchase tracking scope.

== Upgrade Notice ==

= 1.0.0 =
Existing settings and API keys are preserved. Clear caches after upgrading. Select Portuguese in the user's WordPress language settings to use the pt_PT interface.
