=== Beardo Multisite Analytics for GA4 ===
Contributors: beardotools
Donate link: https://beardo.tools/donate/
Tags: google analytics, GA4, analytics dashboard, multisite, analytics
Requires at least: 6.0
Tested up to: 7.0
Requires PHP: 8.0
Stable tag: 1.7.2
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

A clean GA4 reporting dashboard for WordPress and multisite. No tracking code added. Works alongside any existing GA4 setup.

== Description ==

Beardo Multisite Analytics for GA4 brings your Google Analytics 4 data directly into the WordPress admin — without touching your site's tracking setup.

Unlike most GA4 plugins, this one does **not** add any tracking code or scripts to your site. It is a pure reporting dashboard. If you already have GA4 running via Site Kit, Google Tag Manager, a page builder integration, or manual gtag — this plugin works alongside all of it, no conflict, no duplication.

**What You See at a Glance**

* Users, Sessions, Pageviews, and Average Session Duration
* Traffic Trend chart — visualize traffic patterns over time
* Top 5 Pages by views
* Traffic Sources breakdown — Direct, Organic Search, Referral, Organic Social, and more
* Active Users by Device — desktop, mobile, and tablet
* Active Users by Operating System — Windows, iOS, macOS, Android, Linux, Chrome OS
* Date range selector — Last 7, 30, and 90 days
* Switchable chart types — Ring, Pie, Bar, and Polar views for device and OS data
* AJAX data refresh — charts and metrics update without a page reload
* WCAG 2.1 AA accessible updates

**Network Admin Interface**

* Tabbed interface — Properties, Subsites, Settings, Instructions
* Properties tab — searchable, sortable, paginated list of all GA4 properties in your Google account, with Re-sync and Export CSV
* Subsites tab — shows every subsite with its mapped GA4 property, domain, and a direct Login link; exportable to CSV
* Settings tab — configure cache duration (12 or 24 hours), error notification email addresses, API request logging, and uninstall behavior (preserve or purge all plugin data on removal)

**Single Site**

Each site administrator connects their own Google account and selects the GA4 property for their site. Analytics data is scoped to that property only.

**WordPress Multisite — Network Activated**

When network activated, a single Google account connection at the network level gives the super admin access to all GA4 properties associated with that account. Each subsite can be mapped to its own property. Subsite administrators see only the data for their own site.

**Why Not Just Use Google Analytics Directly?**

You could — but staying in WordPress admin means your team doesn't need Google Analytics access or training. Site owners, editors, and clients get the numbers they actually need without logging into a separate platform.

**No Bloat. No Tracking. No Upsell.**

This is a free, open-source plugin with no premium tier, no license keys, and no persistent upgrade prompts. It does one thing — surfaces GA4 data inside WordPress — and does it cleanly.

**Support & Documentation**

* For support, visit [help.beardo.tools](https://help.beardo.tools)
* Publisher site: [beardo.tools](https://beardo.tools)

**Third-Party Libraries**

This plugin bundles the following open-source library. The minified copy shipped with the plugin is built from the developer source linked below:

* Chart.js v4.5.1 (MIT License) — used for dashboard charts. Source: [https://github.com/chartjs/Chart.js/tree/v4.5.1](https://github.com/chartjs/Chart.js/tree/v4.5.1)

== External Services ==

This plugin connects to Google APIs to fetch analytics reports and list available GA4 properties.

It sends data only when an administrator explicitly connects Google OAuth, tests connection, refreshes properties, or when a user views dashboard analytics data.

Service used:

* Google Analytics Data API (reporting)
* Google Analytics Admin API (property discovery)
* Google OAuth 2.0 endpoints (authentication/token refresh)

Data sent to Google may include:

* Your site's OAuth redirect URI
* OAuth client credentials configured by the administrator
* Selected GA4 property ID
* Requested date range and report dimensions/metrics

Google service documentation and policies:

* [Google Analytics Data API](https://developers.google.com/analytics/devguides/reporting/data/v1)
* [Google Analytics Admin API](https://developers.google.com/analytics/devguides/config/admin/v1)
* [Google API Services User Data Policy](https://developers.google.com/terms/api-services-user-data-policy)
* [Google Privacy Policy](https://policies.google.com/privacy)

== Installation ==

**Single Site**

1. Upload the plugin to `/wp-content/plugins/multisite-analytics-ga4` or install via the WordPress Plugins screen
2. Activate the plugin through the Plugins menu
3. Go to **Settings → GA4 Analytics** and connect your Google account
4. Select the GA4 property for your site
5. Navigate to **Dashboard → GA4 Analytics** to view your data

**WordPress Multisite**

1. Upload the plugin to `/wp-content/plugins/multisite-analytics-ga4`
2. Network activate the plugin from **Network Admin → Plugins**
3. Go to **Network Admin → Settings → GA4 Analytics** and connect a Google account with access to all relevant GA4 properties
4. Map each subsite to its corresponding GA4 property
5. Subsite admins can access their own dashboard under **Dashboard → GA4 Analytics** within their site

== Frequently Asked Questions ==

= Will this work on a single site WordPress install? =

Yes — the plugin works on both single site and multisite installations. On a single site you connect your Google account, select your GA4 property, and the dashboard is ready. The multisite network features activate automatically when the plugin is network activated.

= Does this plugin add GA4 tracking code to my site? =

No. This is a reporting dashboard only. It reads data from the GA4 API and displays it in your WordPress admin. It does not add any JavaScript, tracking snippets, or gtag code to your frontend. Your existing GA4 tracking setup — whatever it is — remains unchanged.

= I already use Site Kit / MonsterInsights / Google Tag Manager. Will there be a conflict? =

No conflict. Because this plugin does not touch your tracking setup, it works alongside any existing GA4 implementation. You can use it to add a clean admin dashboard view without replacing or interfering with your current setup.

= Do I need a GA4 property already set up? =

Yes. This plugin connects to an existing GA4 property via the Google Analytics Data API. You will need a Google Analytics 4 property with data already flowing into it. Universal Analytics (UA) properties are not supported.

= What Google permissions does the plugin request? =

The plugin requests read-only access to your Google Analytics data. It cannot modify your GA4 property, create events, or change any settings in your Google account.

= Does my analytics data pass through your servers? =

No. Data is fetched directly from the Google Analytics Data API to your WordPress installation using your own Google account credentials. No data passes through Beardo.Tools servers.

= Does this work on WordPress.com? =

No. This plugin requires a self-hosted WordPress installation (wordpress.org) with the ability to install custom plugins.

= What versions of WordPress and PHP are required? =

WordPress 6.0 or later and PHP 8.0 or later.

= Can subsite admins on a multisite network see other sites' data? =

No. When network activated, each subsite is mapped to a specific GA4 property. Subsite administrators see only the analytics for their own site. Only the super admin has access to the network-level overview.

= Does it work on both subdomain and subdirectory multisite installs? =

Yes. The plugin works on both subdomain (site1.example.com) and subdirectory (example.com/site1) multisite configurations.

= What date ranges are available? =

The dashboard includes a date range selector with three options: Last 7 Days, Last 30 Days, and Last 90 Days.

= Can I change the chart style? =

Yes. The Traffic Sources, Active Users by Device, and Active Users by OS panels each include a chart type selector. You can switch between Ring, Pie, Bar, and Polar chart styles.

= What happens to my data if I uninstall the plugin? =

You control this. The Settings tab includes an Uninstall Behavior option. When checked, uninstalling the plugin preserves all OAuth credentials, property mappings, and cached data — useful if you plan to reinstall or troubleshoot. When unchecked, uninstalling removes all plugin data and logs completely. In multisite, only network administrators can change this setting.

= Where are logs stored? =

When debug logging is enabled, logs are stored in `/wp-content/uploads/ga4-logs/`.

= Where can I get support? =

Support is available at [help.beardo.tools](https://help.beardo.tools). You can also visit beardo.tools for additional documentation.

== Screenshots ==

1. Main dashboard — summary metrics (Users, Sessions, Pageviews, Avg. Duration) and Traffic Trend chart
2. Top 5 Pages table, Traffic Sources pie chart, Active Users by Device, and Active Users by OS panels
3. Settings page — Google account connection and GA4 property selection
4. Assigning a GA4 property to a subsite in a multisite network

== Changelog ==

= 1.7.2 =
* Fix: The "Clear Cache" button on single-site installs did nothing — its click handler was only bound to the multisite button's element id. Both buttons are now handled.
* New: Dashboard reports now exclude GA4 ghost/referral spam (fake hits sent with a foreign or blank hostname, e.g. "trafficheap.cc") by restricting every report to each GA4 property's real hostnames. Those hostnames are fetched automatically from the property's GA4 data streams (so it works on single-site and domain-mapped installs); if they can't be determined, reports are left unfiltered rather than blanked. Overridable via the `beardo_ga4_report_hostnames` and `beardo_ga4_enable_report_hostname_filter` filters.

= 1.7.1 =
* Fix: The 1.7.0 upgrade could skip the data migration (it ran on activation before recording completion), leaving the new install without the network OAuth connection. The migration now runs correctly on activation and re-runs automatically when upgrading from 1.7.0 to recover the connection (if the prior data is still present).
* Change: The migration is now non-destructive — it copies the old "ga4_" settings to the new keys and leaves the originals in place. Because the plugin slug changed, moving from a pre-1.7.0 build is a side-by-side install; this keeps the older build working and the move reversible. The old keys are removed only when the plugin is uninstalled.

= 1.7.0 =
* Compliance: Renamed all internal functions, classes, constants, options, hooks, AJAX actions, nonces, and script handles to use the unique "beardo_ga4_" / "Beardo_GA4_" prefix (was the too-short "ga4" prefix), per WordPress.org plugin guidelines
* Data migration: Existing settings, selected properties, and the network OAuth connection are migrated automatically on upgrade; encrypted tokens and credentials are transparently re-keyed, so no reconnection is required
* Compatibility: Removed the remaining inline <style> block from the error-notification email; all email styling is now inline per-element (standard for HTML email)
* Note: The OAuth callback action name changed; if you reconnect Google after upgrading, copy the updated Redirect URI shown on the settings page into your Google Cloud Console (existing connections continue to work)

= 1.6.0 =
* Renamed plugin to "Beardo Multisite Analytics for GA4"
* Removed the optional compact dashboard widget; analytics now live solely on the dedicated GA4 Analytics page
* Compatibility: Moved all admin scripts and styles to the standard enqueue APIs (wp_enqueue_script / wp_localize_script / wp_add_inline_style)
* Updated bundled Chart.js to v4.5.1
* Security: Hardening audit performed by Get Shield Security
* Security: Hardened nonce verification, capability checks, and output escaping across AJAX handlers and settings pages
* Security: Improved sanitization of all user-supplied inputs at system boundaries
* Security: Restricted uninstall cleanup to network administrators only
* Security: Reviewed OAuth callback and token handling for injection and SSRF risks

= 1.5.4 =
* Maintenance: Version bump and packaging update

= 1.5.3 =
* Maintenance: Compliance and packaging maintenance update

= 1.5.2 =
* Maintenance: Release packaging workflow and QA improvements

= 1.5.1 =
* Bug fix: Dashboard widget device and OS charts missing when only core cache is present

= 1.5.0 =
* UI: Converted Subsites tab to WP_List_Table with search, sort, and pagination
* UI: Added Login column linking directly to each subsite's wp-admin
* UI: Trimmed trailing slash from domain display
* Bug fix: Ensured Tabler icon sprite loads correctly on Network Settings screen

= 1.4.0 =
* UI: Network settings refactored into tabbed interface — Properties, Subsites, Settings, Instructions
* Feature: Properties tab — searchable, sortable, paginated list of all available GA4 properties
* Feature: Subsites tab — active subsites view showing site name, domain, GA4 property, and Login shortcut
* Feature: CSV export on both Properties and Subsites tabs
* Feature: Re-sync button to pull newly added GA4 properties from Google
* UI: Added plugin Settings link in the Plugins list

= 1.3.0 =
* Security: Encryption of stored OAuth credentials completed (AES-256-CBC)

= 1.2.x =
* UI: Refined single-site admin flow introduced in 1.1.0
* Feature: Groundwork for CSV export and tabbed analytics interface
* Maintenance: Stability improvements and code cleanup

= 1.1.0 =
* Feature: Added single-site support — settings available in main admin on non-multisite installs
* UI: Improved OAuth error notices with actionable guidance
* Security: Minor security hardening and legacy callback removal

= 1.0.0 =
* Initial release
* Network-level OAuth authentication
* Per-subsite GA4 property selection
* Smart caching system (12 or 24 hour configurable TTL)
* API request logging with 30-day auto-rotation (stored in /wp-content/uploads/ga4-logs/)
* Error notification emails — configurable recipient list
* Uninstall behavior control — choose to preserve or purge all plugin data on removal
* WCAG 2.1 AA accessibility compliance
* Mobile responsive design

== Upgrade Notice ==

= 1.7.2 =
Maintenance release: fixes the single-site Clear Cache button and excludes GA4 referral/ghost spam from dashboard reports. Safe to update; no action required.

= 1.6.0 =
Security hardening update. Recommended for all users.
