=== GIA — GA4 Ecommerce Tracking for WooCommerce ===
Contributors: userelements
Tags: google analytics, woocommerce, ga4, ecommerce tracking, consent mode
Requires at least: 6.0
Tested up to: 6.8
Stable tag: 0.5
Requires PHP: 8.0
Requires Plugins: woocommerce
License: GPLv2 or later
License URI: http://www.gnu.org/licenses/gpl-2.0.html

Complete GA4 ecommerce tracking for WooCommerce — every funnel event, server-side purchase backup, Consent Mode V2. No Tag Manager. No bloat.

== Description ==

**Paste your Measurement ID. Get trustworthy WooCommerce GA4 ecommerce data.**

GIA GA4 is a measurement-quality layer between WooCommerce and Google Analytics 4 (optionally Google Ads). It fires the full recommended ecommerce funnel, enriches every line item, backs up purchases server-side, and respects consent — without Google Tag Manager, without a data team, and without turning WordPress into a profit or attribution platform.

= What GIA GA4 is =

* **Complete GA4 ecommerce schema** — not just purchase, but the real shopping and checkout funnel
* **Reliable revenue** — browser + Measurement Protocol, with `session_id`, `event_id`, and consent-aware server sends
* **Better item data** — categories, brand, GTIN, discounts, list attribution, classic templates and WooCommerce Blocks
* **GDPR-ready by default** — Consent Mode V2, CMP bridges, geo rules, and a built-in banner
* **Store-owner UX** — onboarding wizard, verification tools, and a lightweight dashboard for setup and shop pulse

GA4 stays the system of record. GIA GA4 feeds it well; it does not replace it.

= What GIA GA4 is not =

GIA GA4 deliberately avoids feature creep. It is **not**:

* A profit, COGS, or margin-by-channel tool
* A journey analytics or multi-touch attribution platform
* A Meta CAPI, TikTok, or ad-spend ingestion hub
* A heavy BI dashboard that duplicates GA4

The built-in dashboard gives operational context — weekly order insights, view-to-purchase, top customers — not a second analytics product inside wp-admin.

= Who this is for =

* **WooCommerce merchants** who want complete GA4 ecommerce without hiring someone for GTM
* **Stores with a GA4 ≠ orders gap** who need Measurement Protocol backup and deduplication
* **EU/UK shops** that need Consent Mode V2 without wrestling CMP + gtag
* **Growth-minded stores** that optionally want Google Ads purchase conversions on the same stack

**Not primarily for:** agencies running custom GTM containers, or merchants who want P&L-by-channel inside WordPress.

= Why GIA GA4 vs other WooCommerce GA4 plugins =

Most alternatives stop at purchase (and maybe add-to-cart). GIA GA4 goes deep on **measurement quality**:

* Full funnel completeness (`view_item_list` through `purchase` and `refund`)
* Rich `items[]` parameters on cart and checkout events
* First-class WooCommerce Blocks cart and checkout support
* Server-side purchase and refund backup with deduplication
* Consent Mode V2 and CMP compatibility out of the box

= GA4 ecommerce events =

**Discovery & product**

* `view_item_list` — Shop, category, and tag archives (`item_list_id` / `item_list_name`)
* `view_item` — Product pages and variable-product variant changes
* `select_item` — Product clicks from classic shop grids (list context persists through the funnel)
* `view_search_results` — On-site product search terms (Extra GA4 events)
* `view_promotion` — On-sale products and WooCommerce store notices

**Cart**

* `add_to_cart` — AJAX, form submit, and WooCommerce Blocks cart (full item payloads)
* `remove_from_cart` — Cart page, mini-cart, and Blocks cart
* `view_cart` — Cart page and Blocks cart

**Checkout**

* `begin_checkout` — Classic and Blocks checkout
* `add_shipping_info` — Shipping method selected
* `add_payment_info` — Payment method selected
* `purchase` — Thank-you page with `transaction_id`, revenue, tax, shipping, coupons, payment method, new vs returning customer, and `event_id` for deduplication
* `payment_failure` — Checkout validation and payment errors (always tracked; classic + Blocks)
* `coupon_applied` / `coupon_removed` — Coupon usage
* `select_promotion` — Coupon codes applied at checkout

**Post-purchase & account**

* `refund` — When a refund is processed in WooCommerce (browser + server)
* `login` / `sign_up` — Optional (enable **Extra GA4 events**)
* `exception` — 404 pages (optional)

**WooCommerce Subscriptions** (when the extension is active)

* `subscription_started`, `subscription_cancelled`, `subscription_expired`
* Renewal orders sent as `purchase` via Measurement Protocol

**Optional extras** (off by default — **Extra GA4 events** setting)

* `cart_time_spent` — Seconds on cart/checkout before leaving

Core funnel events can be toggled individually in **Settings → Events** to reduce volume. Checkout errors, coupons, shipping, and payment events are always tracked.

= Rich GA4 item data =

Every funnel event can include detailed product line items:

* Hierarchical categories (up to 5 levels)
* Brand (auto-detects common brand taxonomies)
* GTIN / EAN / UPC when stored in product meta
* Variant, image URL, stock status
* Sale `discount` amount on discounted products
* `item_list_id` and `item_list_name` carried from list views through add-to-cart and purchase
* Product ID or SKU as `item_id` (setting)
* Product Bundles use minimum bundle price in item data

Works on **classic templates** and **WooCommerce Blocks** cart/checkout via the Store API.

= Server-side purchase & refund tracking =

Browser tags are blocked by ad blockers and strict privacy settings. GIA GA4 mirrors `purchase` and `refund` from your server using the **GA4 Measurement Protocol**.

* Saves GA4 `client_id` and `session_id` on the order at checkout
* Sends `event_id` on server hits to deduplicate with browser `purchase` events
* Retries failed sends via Action Scheduler
* Respects stored analytics consent before server sends
* Optional multi-currency normalization for foreign-currency orders (WOOCS / WooPayments rates)
* Configurable trigger: order **Completed** or **Processing**

Add your **GA4 API Secret** in settings and use the built-in **Verify tracking setup** tool.

= Consent Mode V2 =

* gtag loads with consent defaulting to **denied** (configurable)
* Built-in consent banner (auto-hides when a CMP is detected)
* Geo-aware defaults: EU/EEA/UK → denied, US → granted (optional)
* Bridges: CookieYes, Complianz, Cookiebot, and the [WP Consent API](https://wordpress.org/plugins/wp-consent-api/)
* Order-level consent stored for server-side tracking decisions

= Google Ads (optional) =

* Fire `conversion` on purchase with your AW- account ID and conversion label
* Enhanced Conversions: hashed billing data sent with purchase (same consent rules as GA4)

= Other optional features =

* Google Tag Manager container ID (disable base gtag when GA4/GTM is loaded elsewhere)
* Server-side gtag proxy (extends cookie lifetime, reduces blocker impact)
* Cross-domain linker settings (domains + incoming parameters)
* Transactional email link UTM tagging
* First-touch UTM / `gclid` / `fbclid` saved to order meta + Traffic Source admin column
* Exclude store administrators from tracking
* GA4 DebugView mode
* Gross vs net revenue on purchase events
* Accepts `G-` and `GT-` Measurement IDs
* HPOS (High-Performance Order Storage) compatible
* Onboarding wizard on first activation
* Admin warnings when Google Analytics for WooCommerce or Site Kit may duplicate tracking

= Built-in dashboard (operational, not BI) =

Admin menu: **GIA GA4 → Analytics**

* **Overview** — Setup wizard, tracking verification, and weekly WooCommerce insights (revenue, refunds, customer mix, geo, checkout risk, tracking gap vs GA4 when Site Kit is connected)
* **Traffic** — GA4 sessions, channels, and landing pages via [Site Kit](https://wordpress.org/plugins/google-site-kit/) when installed (optional)
* **Products** — Local view-to-purchase report (no Google API required for view counts)
* **Customers** — Top customers by lifetime spend
* **Settings** — Full configuration (also at WooCommerce → Settings → Integrations, redirected to GIA GA4 settings)

= Known gaps =

Transparent limits aligned with the measurement-quality focus:

* `select_item` list attribution on **Block Product Collection** grids is not yet supported (classic shop grids are supported)
* No `add_to_wishlist` or deep promotion CMS integration unless store-specific

These are extensions of the same GA4 data-quality goal, not a product pivot.

= Privacy =

* Registers WordPress personal data export and erasure handlers
* Checkout error logs and product view counters auto-expire (configurable retention: 30–365 days)
* Enhanced conversion data is hashed before transmission; not stored by this plugin

== External Services ==

This plugin connects to external services to provide analytics functionality. By using this plugin, you agree to the terms and privacy policies of these services.

**1. Google Analytics 4 (required for tracking)**

* Purpose: Records ecommerce events, sessions, and conversions
* Data sent: Page views, ecommerce events, hashed customer data (if Enhanced Conversions enabled), client/session identifiers
* Domains: `www.googletagmanager.com`, `www.google-analytics.com`, `region1.google-analytics.com`
* Terms: [Google Analytics Terms](https://marketingplatform.google.com/about/analytics/terms/us/)
* Privacy: [Google Privacy Policy](https://policies.google.com/privacy)

**2. GA4 Measurement Protocol (recommended)**

* Purpose: Server-side `purchase` and `refund` event delivery when browser tracking is blocked
* Data sent: Order value, line items, transaction ID, client ID, session ID, event ID
* Endpoint: `https://www.google-analytics.com/mp/collect`
* Terms/Privacy: Same as Google Analytics above

**3. Google Ads (optional)**

* Purpose: Purchase conversion signals for Smart Bidding
* Data sent: Conversion value, transaction ID, hashed customer data (if enabled)
* Domains: `www.googletagmanager.com`
* Terms: [Google Ads Terms](https://ads.google.com/home/terms/)
* Privacy: [Google Privacy Policy](https://policies.google.com/privacy)

**4. Google Tag Manager (optional)**

* Purpose: Tag deployment when you manage GA4 through GTM
* Domain: `www.googletagmanager.com`
* Only loaded when a GTM container ID is configured

**5. Google Site Kit (optional — dashboard only)**

* Purpose: Display GA4 traffic reports inside the GIA GA4 dashboard
* Only used when Site Kit is installed and Analytics is connected
* Plugin: [Google Site Kit](https://wordpress.org/plugins/google-site-kit/)

== Installation ==

1. Install and activate **WooCommerce**
2. Install and activate **GIA — GA4 Ecommerce Tracking for WooCommerce**
3. Complete the onboarding wizard (or go to **GIA GA4 → Settings**)
4. Enter your **GA4 Measurement ID** (`G-XXXXXXXXXX` or `GT-XXXXXXXXXX`)
5. (Recommended) Add your **GA4 API Secret** for server-side purchase tracking
6. Visit your store in an incognito window and confirm events in GA4 **Realtime** or **DebugView**

== Frequently Asked Questions ==

= Does this work without Google Tag Manager? =

Yes. That is the default path. Enter your GA4 Measurement ID and events fire via gtag.js. GTM is optional for stores that already use it.

= Why are GA4 purchases lower than WooCommerce orders? =

Common causes: ad blockers, consent denied, or comparing GA4 Realtime to orders still processing. Enable the **GA4 API Secret** for Measurement Protocol backup and set **Purchase trigger** to match when you consider an order final. Browser and server events share the same `event_id` so GA4 deduplicates instead of double-counting.

= Does it support WooCommerce Blocks checkout? =

Yes. Cart and checkout blocks are supported through the WooCommerce Store API and dedicated Blocks JavaScript. `view_cart`, `begin_checkout`, cart changes, coupons, shipping, payment, and checkout errors are tracked on block-based stores. WooCommerce Blocks' built-in Google Analytics script is dequeued to prevent duplicate events.

= How does purchase deduplication work? =

Browser and server `purchase` events share the same `event_id` (`giawc_purchase_{order_number}`). GA4 deduplicates matching event IDs from the same client.

= Is it GDPR compatible? =

The plugin implements Google Consent Mode V2, defaults consent to denied, integrates with popular CMPs, and can apply geo-based consent defaults. You are responsible for your store's legal compliance and privacy policy.

= Does it work with WooCommerce Subscriptions? =

Yes. Subscription lifecycle events fire in the browser; renewal payments without a session are sent as `purchase` via Measurement Protocol.

= What is the view-to-purchase report? =

The Products tab compares locally counted product page views with WooCommerce order line items — useful for spotting products with high views but low conversion. View counts do not require Google API access.

= Can I use SKU instead of product ID in GA4? =

Yes. Change **Product identifier** in settings to SKU. List attribution still works via internal product ID mapping.

= Does GIA GA4 track profit or ad spend? =

No. GIA GA4 focuses on accurate GA4 ecommerce measurement. Use GA4, Google Ads, or dedicated finance tools for profitability and attribution analysis.

== Screenshots ==

1. Settings — Connect GA4 in a few steps
2. eCommerce Dashboard Stats
3. Settings WooCommerce events
4. Measurement ID, API secret, consent, and advanced options
5. Products stats
6. Customer statistics.


== Changelog ==

= 0.5 =
* Improvement: Measurement Protocol sends `session_id`, `event_id`, and `engagement_time_msec` on purchase/refund
* Improvement: `item_list_id` / `item_list_name` persist from `select_item` through cart and purchase events
* Improvement: Full `items[]` payloads on add-to-cart and remove-from-cart (classic + Blocks)
* Improvement: Sale `discount` on GA4 line items when products are on sale
* Improvement: `view_promotion` for on-sale products and store notices
* Improvement: Blocks checkout uses official WooCommerce cart/payment stores and checkout failure events
* Improvement: `payment_failure` documented as always-on (not behind Extra GA4 events)
* Fix: Blocks `add_shipping_info` and `add_payment_info` used non-existent store APIs (corrected against WooCommerce core)
* Fix: Mini-cart remove links now tracked via `data-ga4-item` attribute
* Fix: Product JSON in HTML attributes uses WooCommerce `wc_esc_json()` for safe encoding
* Refocus: GA4 ecommerce event tracking (removed profit/COGS, journey analytics, Meta CAPI, ad spend)
* Renamed from Trackify to GIA GA4
* Streamlined dashboard: Overview weekly insights, Traffic, Products, Customers, Settings
* Removed profit columns from product reports and weekly insights
* Fix: Dequeue WooCommerce Blocks built-in Google Analytics script to prevent duplicate gtag configuration and double-fired events on block cart/checkout
* Fix: Validate order key on thank-you page before firing browser purchase events
* Improvement: Blocks cart/checkout prices use Store API line totals and cart totals (WooCommerce minor-unit format)
* Improvement: Accept Google Tag measurement IDs (`GT-`) in addition to `G-` IDs
* Improvement: Blocks mini-cart tracking on all WooCommerce Blocks stores with deduplicated remove-from-cart events
* Improvement: Per-event enable/disable toggles for core GA4 ecommerce events
* Improvement: Cross-domain linker settings (domains + incoming parameters)
* Improvement: Product Bundles use minimum bundle price in GA4 item data
* Improvement: Admin warning when Google Analytics for WooCommerce or Site Kit snippet may duplicate GIA GA4 tracking
* Improvement: Settings page reorganized into Connection, Privacy, Events, and Advanced tabs
* Fix: Tabbed settings panels render fields correctly (WooCommerce table wrapper compatibility)
* Richer GA4 item data, improved server-side deduplication, and Blocks checkout tracking fixes. Recommended for all stores.


= 0.4 =
* Improvement: Tabbed analytics dashboard (overview, products, customers)
* Improvement: First-touch UTM attribution saved to order meta
* Improvement: HPOS-compatible traffic source queries
* Improvement: Server-side purchase deduplication and new vs returning customer on purchase
* Improvement: Coupon, shipping, payment, and payment failure checkout events
* Improvement: Product image, GTIN, hierarchical categories, and brand in item data
* Improvement: WordPress script enqueue compliance (`wp_add_inline_script`)
* Improvement: Namespace prefix `giawc_` throughout

= 0.3 =
* Improvement: WordPress.org compliance updates (prefixes, PHPCS, enqueue standards)
* Improvement: Database query optimization and HPOS compatibility
* Removed: Meta and TikTok tracking

= 0.2 =
* Fix: PHP fatal error in settings API compatibility
* Improvement: Code standards compliance

= 0.1 =
* Initial release