=== Heretek Analytics ===
Contributors: Heretek-AI
Tags: analytics, google analytics, ga4, privacy, apexcharts
Requires at least: 5.6.0
Tested up to: 6.9
Stable tag: 12.3.0
Requires PHP: 7.4
License: GPLv3
License URI: https://www.gnu.org/licenses/gpl-3.0.html

A 100% self-hosted Google Analytics 4 plugin for WordPress. Interactive dark cyber-theurgy dashboard powered by ApexCharts, real-time telemetry, author performance leaderboards, and direct GA4 Data API integration. Zero subscriptions, zero phone-homes, zero paywalls.

== Description ==

= Heretek Analytics =

Heretek Analytics is an open-source, telemetry-free fork of Google Analytics for WordPress, distributed under the GNU General Public License v3.0 (GPLv3).

Unlike commercial distributions, Heretek Analytics does not phone home to a third-party SaaS, does not gate capabilities behind a license key, and does not relay reporting traffic through external proxies. The plugin speaks directly to Google Analytics 4 on behalf of your site.

= What you get =

* **Augur Telemetry Cockpit** — Interactive ApexCharts area splines, multi-metric switcher (Sessions, Users, Views, Engagement), channels and devices donut charts.
* **GA4 Realtime Live Stream** — Active users in the last 30 minutes, 30-minute minute-by-minute histogram, live radar telemetry, auto-refreshing polling loop.
* **Period-over-Period Growth Deltas** — Real-time comparative percentage calculations against previous date windows.
* **Zero-Reload SPA Date Filtering** — Today, Yesterday, Last 7 Days, Last 30 Days, Last 90 Days, and custom calendar ranges with zero page reloads.
* **Authors Leaderboard** — Per-author traffic breakdown, visual bar chart, and CSV/JSON export.
* **Executive WP Admin Dashboard Widget** — Embedded 30-day telemetry summary directly on `wp-admin/index.php`.
* **Direct GA4 Data API Gateway** — REST endpoint mints JWTs with service account keys and exchanges for OAuth2 tokens directly with Google Analytics Data API.
* **Smart Transient Quota Protection** — 15-minute historical, 3-minute today, and 30-second realtime caching with manual cache-busting sync.
* **Core GA4 tracking (gtag.js)** — automatic page-view, scroll, download, affiliate-link, form-submission, author dimensions, and AMP tracking.
* **Google Consent Mode v2** — EEA compliance helpers in `includes/admin/eea-compliance.php`.
* **Server-side GA4 Measurement Protocol** — `Heretek_Analytics_Measurement_Protocol_V4` (with `MonsterInsights_Measurement_Protocol_V4` backward alias).
* **Native GitHub Releases updater** — automatic, no license keys.
* **Settings export** — JSON download from the Tools page.

== Installation ==

1. Download the latest `heretek-analytics.zip` release from https://github.com/Heretek-AI/Heretek-Analytics/releases
2. In your WordPress admin, go to **Plugins** > **Add New** > **Upload Plugin**.
3. Select `heretek-analytics.zip` and click **Install Now**.
4. Activate the plugin.
5. In your admin sidebar, navigate to **Heretek Analytics** > **Settings** and fill in three fields:
   * **GA4 Measurement ID** — `G-XXXXXXXXXX`
   * **GA4 Property ID** — numeric (find under Admin > Property settings > Property ID)
   * **Service Account JSON** — a Google Cloud service account key (see the FAQ below).

== Frequently Asked Questions ==

= Do I need a license key? =
No. Heretek Analytics is 100% free software licensed under GPLv3. There are no paid tiers, no license keys, and no subscriptions.

= Does this plugin send data to third-party servers? =
No. Heretek Analytics never contacts monsterinsights.com, exactmetrics.com, or any other third-party SaaS. The only outbound HTTP requests are to Google (`googletagmanager.com`, `analyticsdata.googleapis.com`, `oauth2.googleapis.com`) for GA4 tracking and reporting.

= How do I create a Google Cloud service account for the GA4 Data API? =
1. Open Google Cloud Console and pick (or create) a project.
2. APIs & Services -> Library -> enable "Google Analytics Data API".
3. IAM & Admin -> Service Accounts -> Create Service Account, then Keys -> Add Key -> Create new key -> JSON. Save the downloaded JSON file.
4. In GA4, open Admin -> Property access management and add the service-account email (it looks like `[email protected]`) as a Viewer.
5. Paste the entire contents of the JSON file into the "Service Account JSON" field on the Settings page.

= How do updates work? =
Heretek Analytics includes an integrated GitHub Releases updater. When a new version is tagged on GitHub (`Heretek-AI/Heretek-Analytics`), your WordPress admin will notify you under Dashboard -> Updates and allow one-click in-place upgrading.

== Changelog ==

= 12.3.0 =
* Google Analytics Admin API Schema Forge: Service Account can now automatically query and provision GA4 custom dimensions directly via `analyticsadmin.googleapis.com` (`author_id`, `author`, `character`, `chapter`, `location`, `post_tag`, `category`, `post_type`).
* Comic Easel & Extended Taxonomy Tracking: Frontend `gtag.js` now dynamically emits Comic Easel taxonomies (`characters`, `chapters`, `locations`) as well as tags, categories, and author metadata with dual-scope emission (both event parameters and user properties).
* Instant Hybrid Attribution Engine: Resolves GA4 `(not set)` author and taxonomy gaps by mapping GA4 top page paths against WordPress post IDs and taxonomy terms for immediate historical attribution without waiting 24-48h for GA4 dimension populating.
* Authors & Content Taxonomy Dashboard: Added multi-taxonomy navigation tabs (Authors, Comic Characters, Comic Chapters, Tags) with live Schema Forge auto-provisioning bar and custom CSV export.
* Reports Cockpit Characters Leaderboard: Embedded reactive character performance leaderboard into the Authors & Content dashboard tab.
* Schema Forge Status & Provisioning UI in Settings: Integrated live custom dimension registry health check and 1-click auto-provisioning in Google Cloud credentials card.

= 12.2.0 =
* Complete visual & architectural overhaul: Blood & Steel dark cyber-theurgy aesthetic with obsidian void surfaces (#07070a), tech-bracket corners, and pulsing telemetry beacons.
* Vendored high-performance ApexCharts area splines, donut charts, and author ranking bars.
* Added live GA4 Realtime Stream with 30-minute minute-by-minute histogram, real-time user counter, and automated 30s background polling loop.
* Implemented period-over-period comparative delta calculation (+/- %) across all core telemetry KPIs against the preceding window.
* Added Zero-Reload SPA date-range filtering (Today, Yesterday, 7D, 30D, 90D, Custom) with instant reactive chart and KPI updates.
* Upgraded Reports Cockpit to a 5-tab unified command center: Master Augur, Realtime Live, Authors & Content, Traffic & Acquisition, and Tech & Audience.
* Added native executive Telemetry Summary dashboard widget on wp-admin/index.php.
* Implemented smart transient quota protection (15m historical, 3m today, 30s realtime) with manual cache-busting sync action.
* Pruned ~2,200 lines of dead MonsterInsights SaaS routes and redundant AJAX handlers in favor of direct local REST gateway.
* Added CSV and JSON export capabilities for reporting data and author leaderboards.

= 12.1.0 =
* New: author tracking on singular views — gtag config keys `author` (display name) and `author_id` (numeric WP user ID) emitted alongside the existing page-view config. Pair with User-scoped GA4 Custom Dimensions of the same API names to surface per-author reporting.
* New: date-range filter on the Reports page — two `<input type="date">` fields (start, end) with an Apply / Reset form. Server-side `$_GET` round-trip; no JS, no AJAX. The H1 reflects the chosen range.
* New: Top Authors panel on the Reports dashboard, plus a dedicated **Heretek Analytics → Authors** sub-page (`admin.php?page=monsterinsights_authors`) with a per-author ranking table (Sessions / Users / Page Views / Engaged Sessions) and a CSV export (`?export=csv`).

= 12.0.0 =
* Stand-alone, no SaaS: dropped every call to monsterinsights.com / exactmetrics.com / app.monsterinsights.com / connect.monsterinsights.com / upgrade.monsterinsights.com / plugin-cdn.monsterinsights.com / ai-api.monsterinsights.com.
* Removed the entire Vue 3 admin app (lite/assets/vue3/ and pro/assets/vue3/). Settings, Reports, Tools, Addons, and About pages are now pure PHP.
* Removed MonsterInsights Connect / API-Auth / API-Request / Notifications / Feature-Feedback / Charitable / Last-Seen / Usage-Tracking / Review / Setup-Checklist / Onboarding classes.
* Removed all upstream Pro-modules (eCommerce, Forms, Media, Custom Dimensions, PPC, EU Compliance) and the popular-posts / gutenberg / email-summaries sub-systems.
* Added GA4 Data API direct integration: the REST gateway mints a service-account JWT, exchanges it for an OAuth2 token, and queries `analyticsdata.googleapis.com/v1beta/properties/{id}:runReport`.
* Settings page now has a three-field form (Measurement ID + GA4 Property ID + Google Cloud service account JSON) with a "Verify Credentials" button that confirms service-account access.
* Reports page is server-rendered with real GA4 data — daily sessions chart, top-pages table, top-countries table.
* New Tools page (settings export + environment read-out) and About page.

= 11.2.0 =
* Complete retheme to Heretek "Blood & Steel" aesthetic.
* Integrated native GitHub Releases updater (Heretek-AI/Heretek-Analytics).
* Purged all upstream telemetry, promotional rotators, and phone-home beacons.
* Autonomous Local REST Reporting Gateway for direct GA4 Data API queries.
* Full Pro/Agency tier reporting modules unlocked.
