WPCalibrate GA4 Analytics

Lightweight, privacy-conscious Google Analytics 4 (GA4) integration for WordPress with Google Consent Mode v2, automatic event tracking, optional WooCommerce ecommerce tracking, administrator diagnostics, and live event simulation.

Table of Contents

• About
• Why WPCalibrate?
• Key Features
  • Zero Database Overhead
  • Google Consent Mode v2 Support
  • Granular Automatic Event Tracking
  • WooCommerce Ecommerce & Deduplication
  • Demo GA4 Sandbox & Live Event Simulator
  • Intelligent Exclusion Engine
  • Duplicate Tag Collision Diagnostics
  • WordPress Dashboard 1-Click Updates
• Architecture & Technical Method
• Installation & Quick Start
• Configuration Guide
  • Overview Tab
  • General Settings
  • Events Tracking
  • WooCommerce Ecommerce
  • Google Consent Mode v2
  • Diagnostics & Live Simulator
  • License & Support
• WordPress Dashboard Automatic Updates
• Testing & Quality Assurance
• Changelog
• Security & Privacy
• Support & Community
• License

About

WPCalibrate GA4 Analytics is an enterprise-grade, high-performance WordPress plugin designed to connect your website with Google Analytics 4 without the bloat, slow page load speeds, and database clutter associated with legacy analytics plugins.

Most analytics plugins load heavy dashboard charts, poll remote Google APIs, and write analytics data into your WordPress MySQL database on every visitor page hit. WPCalibrate GA4 Analytics takes the opposite approach: zero database writes on frontend page loads, non-blocking asynchronous tag emission, strict PII protection, and pure client-side analytics dispatch.

Why WPCalibrate?

Key Features

Zero Database Overhead

• Executes zero INSERT, UPDATE, or DELETE queries during standard frontend visits.
• All configuration settings are cached in standard WordPress options with autoloading.
• Browser-based execution ensures 100% caching compatibility with LiteSpeed, WP Rocket, Cloudflare, Fastly, and Nginx microcaching.

Google Consent Mode v2 Support

• Declares standardized Google Consent Mode v2 signals prior to Google tag initialization:
  • analytics_storage
  • ad_storage
  • ad_user_data
  • ad_personalization
• Two Operating Modes:
  • Basic Consent Mode: Blocks Google tag execution completely until explicit user consent is registered.
  • Advanced Consent Mode: Loads Google tag in consent-aware mode, emitting cookieless pings until consent is granted.
• Seamless bridge with the WordPress Consent API (wp-consent-api), listening to cookie banner updates automatically.

Granular Automatic Event Tracking

Toggle tracking for individual user interactions without writing a single line of JavaScript:

• Outbound Link Clicks: Identifies external URLs and dispatches click events with clean destination targets.
• File Downloads: Captures downloads matching standard document, spreadsheet, and media extensions (.pdf, .zip, .docx, .xlsx, .mp4, etc.).
• Site Search: Accurately maps internal WordPress search terms (s query parameter) to GA4 search events.
• Scroll Depth: Emits scroll milestones when visitors engage with deep content (90% threshold).
• PII-Safe Form Submissions: Detects form submissions without reading or transmitting form values, customer names, passwords, credit cards, or email addresses.

WooCommerce Ecommerce & Deduplication

• HPOS Compatible: Works natively with High-Performance Order Storage (HPOS) and legacy post storage.
• Full Funnel Events: Tracks view_item, add_to_cart, remove_from_cart, view_cart, begin_checkout, and purchase.
• Purchase Deduplication: Records _wpcalibrate_ga4_purchase_tracked order metadata upon first transaction emission, guaranteeing that shoppers refreshing their order confirmation / thank-you page will never trigger duplicate purchase revenue in GA4.
• Strict PII Redaction: Formats sanitized, currency-converted monetary totals while stripping customer addresses, phone numbers, billing names, and internal notes.

Demo GA4 Sandbox & Live Event Simulator

• One-Click Sandbox Activation: Populates sandbox Measurement ID G-DEMOTEST01, enables tracking, turns on GA4 debug_mode, and disables admin exclusion for instant testing.
• Interactive Live Event Dispatch Simulator: Test 8 standard GA4 events directly inside the WordPress dashboard:
  • page_view
  • view_item
  • add_to_cart
  • begin_checkout
  • purchase
  • search
  • file_download
  • form_submit
• Real-Time Interactive Console: View live timestamped JSON payloads dispatched into dataLayer and streamed to Google Analytics 4 DebugView.
• One-Click Defaults Reset: Return to clean unconfigured settings with a single click.

Intelligent Exclusion Engine

Prevent polluting your production metrics with team or automated traffic:

• Exclude WordPress Administrators (enabled by default).
• Exclude specific User Roles (Editor, Author, Contributor, Shop Manager, etc.).
• Exclude all logged-in users regardless of role.
• Exclude Customizer sessions and post preview views.
• Exclude designated hostnames or IP addresses (e.g., staging.example.com, localhost).

Duplicate Tag Collision Diagnostics

• Automated scanning detects overlapping tags from:
  • Google Site Kit
  • MonsterInsights
  • WooCommerce Google Analytics Integration
  • ExactMetrics
  • WPCode / Insert Headers and Footers
  • Google Tag Manager (GTM)
  • DuracellTomi's GTM4WP
• Displays clear, actionable warnings in the Diagnostics tab to prevent double-counting hits.

WordPress Dashboard 1-Click Updates

• Integrated with GitHub Releases. Whenever a new version is published to this repository, WordPress automatically displays standard update alerts under Dashboard → Updates and Plugins.
• Supports 1-click in-dashboard upgrade without external updater plugins.

Architecture & Technical Method

flowchart TD
    A[Visitor Requests Page] --> B{Eligibility Gatekeeper}
    B -- Admin / Role Excluded --> C[Suppress Tag Output]
    B -- Preview / Customizer --> C
    B -- Hostname Excluded --> C
    B -- Eligible Visitor --> D{Consent Mode v2}

    D -- Basic Mode & Unconsented --> E[Suppress Tag Until Consent Event]
    D -- Advanced Mode / Consented --> F[Emit gtag.js Snippet]

    F --> G[Initialize dataLayer & gtag]
    G --> H[Frontend Tracker: Outbound / Downloads / Searches]
    G --> I{WooCommerce Active?}

    I -- Yes --> J[Ecommerce Tracker: view_item, cart, checkout]
    J --> K{Order Confirmation?}
    K -- Yes --> L{Already Tracked in Order Meta?}
    L -- No --> M[Emit purchase Event & Stamp Meta]
    L -- Yes --> N[Skip Duplicate Purchase]

Installation & Quick Start

Method 1: WordPress Admin Upload (Recommended)

1. Download the latest wpcalibrate-ga4-analytics.zip release from the Releases page.
2. In your WordPress admin, navigate to Plugins → Add New Plugin → Upload Plugin.
3. Choose the downloaded ZIP file and click Install Now.
4. Click Activate Plugin.

Method 2: Git Clone

Clone directly into your WordPress plugins directory:

cd wp-content/plugins/
git clone https://github.com/zeeshanraza-official/wpcalibrate-ga4-analytics.git wpcalibrate-ga4-analytics

Quick 3-Step Setup

1. Enter Measurement ID: Go to WPCalibrate → GA4 Analytics → General and enter your G-XXXXXXXXXX tag ID (or click Use Demo ID for testing).
2. Configure Exclusions: Toggle the admin exclusion and select which environments or user roles should be excluded.
3. Turn On Events & Save: Head to the Events and Ecommerce tabs to activate the interactions you wish to measure, then click Save Settings.

Configuration Guide

1. Overview Tab

The entry dashboard for WPCalibrate GA4 Analytics:

• Live Status Header: Real-time indicator showing whether tracking is active, paused, or in demo sandbox mode.
• Metric Badges: At-a-glance status for Master Tracking, Measurement ID, Google Consent Mode, and WooCommerce compatibility.
• Setup Guide: 3-step walkthrough with direct deep-links to specific settings panels.
• Demo Sandbox Controls: Load demo configuration or launch the live event simulator in one click.

2. General Settings

• Master Tracking: Master kill switch to enable or disable Google tag injection site-wide.
• Measurement ID: Accepts valid Google Analytics 4 stream IDs formatted as G-XXXXXXXXXX.
• Tag Placement: Choose between standard <head> injection (recommended by Google) or footer injection.
• Admin & Role Exclusions: Selectively suppress tracking for admins, custom roles, or all logged-in accounts.
• Hostname Exclusions: Enter staging or development domains separated by commas.
• Debug Mode: Pass debug_mode: true to view incoming parameters in the browser console and GA4 DebugView.

3. Events Tracking

• Outbound Links: Automatically logs external clicks with target URLs and link hostnames.
• File Downloads: Tracks document and media file downloads with file extension detection.
• Site Search: Records internal query strings and results page views.
• Scroll Tracking: Captures 90% engagement scroll milestones.
• Safe Form Submissions: Captures form IDs without recording input values, securing GDPR/CCPA compliance.

4. WooCommerce Ecommerce

• Ecommerce Tracking: Master switch for WooCommerce store analytics.
• Product Views (view_item): Measures single product page views with prices, SKUs, and categories.
• Cart Interactions: Logs add_to_cart and remove_from_cart events.
• Checkout Funnel: Tracks view_cart and begin_checkout.
• Purchase Tracking (purchase): Captures complete transaction payloads with order totals, tax, shipping, and coupons.
• Idempotency Guard: Deduplicates thank-you page reloads.

5. Google Consent Mode v2

• Consent Mode Master Switch: Enables default consent status commands.
• Consent Enforcement Mode: Switch between Basic Mode (complete tag suppression) and Advanced Mode (cookieless pings).
• Default Storage Categories: Configure default permissions for analytics_storage, ad_storage, ad_user_data, and ad_personalization.
• WordPress Consent API: Enables bi-directional listening to cookie management banners (wp_set_consent).

6. Diagnostics & Live Simulator

• Live Event Simulator: Dispatch 8 standard GA4 events with full sample ecommerce payloads.
• Interactive JSON Console: Timestamped JSON viewer displaying payload contents and dispatch timestamps.
• Duplicate Tag Scanner: Analyzes active plugins and alerts you of competing tracking implementations.
• System Information: Displays WordPress, WooCommerce, PHP, and server environment details.

7. License & Support

• Licensing Abstraction: Clean provider interface for marketplace or standalone license verification.
• Support & Docs: Direct links to documentation, WhatsApp support, and technical assistance.

WordPress Dashboard Automatic Updates

This repository is configured for native WordPress dashboard updates. When you install WPCalibrate GA4 Analytics:

1. The plugin periodically checks the public GitHub repository releases API via wpcalibrate_ga4_gh_update transient cache.
2. When a newer version tag (e.g. v1.0.3) is released on GitHub, WordPress displays standard update notifications:
   • In Dashboard → Updates
   • In Plugins table with "Update Now" and "View version details" links
3. Clicking Update Now automatically downloads the verified release ZIP and performs a clean upgrade, preserving your existing configuration settings.

Testing & Quality Assurance

WPCalibrate GA4 Analytics includes an exhaustive automated testing suite:

• 180 Unit & Integration Test Assertions:
  • Regex compliance for Measurement IDs (^G-[A-Z0-9]{4,15}$).
  • Frontend tag suppression during admin, preview, cron, AJAX, and REST requests.
  • Role-based exclusion and hostname wildcard matching.
  • Complete PII scrubbing verification (zero emails, phone numbers, passwords, billing addresses in payloads).
  • Purchase event deduplication and order metadata idempotency.
  • Competing analytics plugin collision detection.
  • Google Consent Mode v2 state transitions.
  • Demo sandbox configuration and event simulation.
  • Clean uninstallation and option retention preferences.
• Zero PHP Syntax Errors: Linted across all codebase files with PHP 8.2 and 8.3 CLI.

To run the automated tests locally:

php tests/test-runner.php

Changelog

[1.0.2] - 2026-10-15

• Demo GA4 Analytics Testing Suite: Added one-click sandbox configuration (G-DEMOTEST01), enabling instant testing without requiring real Google Analytics credentials.
• Live Event Dispatch Simulator: Built-in 8-event interactive dispatcher in the Diagnostics console (page_view, view_item, add_to_cart, begin_checkout, purchase, search, file_download, form_submit) streaming live to GA4 DebugView.
• Real-Time Interactive Console: Added formatted JSON inspector, event counter, and console clear tool.
• GitHub Automatic Updates: Added zero-dependency automatic release updater for 1-click updates from the WordPress dashboard.
• Quality Assurance: Expanded automated test suite to 180 passing assertions.

[1.0.1] - 2026-10-15

• Admin Sidebar Icon Fix: Replaced oversized image with optimized 20x20 base64 SVG data URI conforming strictly to WordPress core #a7aaad dashicon palette with bounding constraints in admin_head.
• Overview Tab: Added dedicated primary overview tab featuring live tracking metrics, 3-step setup guide, purpose & mission statements, and technical method documentation.
• Admin UI Overhaul: Complete dashboard styling redesign featuring accessible CSS toggle switches, grouped cards, live pulsating tracking badges, and responsive layout.

[1.0.0] - 2026-10-15

• Initial production release.
• Core GA4 tracking tag injection (gtag.js) in header or footer.
• Google Consent Mode v2 support with WordPress Consent API integration.
• Automatic event capture for downloads, outbound links, search, and form submissions.
• WooCommerce ecommerce measurement with purchase deduplication.
• Duplicate tag collision diagnostics scanner.
• Settings export/import utilities and safe uninstallation routines.

Security & Privacy

• Strict Nonce & Capability Verification: Every form submission and AJAX endpoint requires valid manage_options permissions and WordPress security nonces.
• Strict PII Protection: Form submission tracking captures only form IDs/classes and never reads or transmits input field values, emails, passwords, or credit card details.
• GDPR & CCPA Compliant: Native Google Consent Mode v2 integration ensures tracking respects regional user consent preferences.
• No Third-Party Tracking: The plugin communicates only with Google Analytics endpoints specified by your own Measurement ID and GitHub Releases for updates.

Support & Community

• Official Website: https://wpcalibrate.com
• Documentation: https://wpcalibrate.com/docs/ga4-analytics
• Issue Tracker: GitHub Issues
• Support Email: support@wpcalibrate.com

License

This project is licensed under the GNU General Public License v2.0 or later - see the license.txt file for details.

Disclaimer: WPCalibrate GA4 Analytics is independently developed by WPCalibrate and is not affiliated with, endorsed by, or sponsored by Google LLC or Automattic Inc.