=== AG Data for PostHog ===
Contributors: levskipg
Tags: posthog, woocommerce, analytics, attribution, ecommerce
Requires at least: 5.8
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 1.5.3
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

PostHog Analytics for WooCommerce. Server-side event tracking, marketing attribution engine, identity stitching, and LTV enrichment.

== Description ==

AG Data for PostHog connects your WooCommerce store to [PostHog](https://posthog.com) — the open-source product analytics platform. Track the complete customer journey from first click to lifetime value, all within PostHog.

= Why AG Data? =

Most WooCommerce analytics plugins give you pageviews and basic events. AG Data gives you a **full marketing attribution engine** — first-touch/last-touch UTM tracking, ad click ID capture (Google, Meta, TikTok, Microsoft, LinkedIn), server-side first-party cookies that survive Safari ITP, and automatic LTV enrichment on every person profile.

= Key Features =

**Server-Side Event Tracking**

* Order Completed, Order Refunded, Order Status Changed
* Deduplication prevents double-counting
* Blocking API calls ensure delivery before marking as tracked
* Works with all payment gateways and checkout flows

**Frontend Event Tracking**

* Product Viewed, Product List Viewed, Products Searched
* Product Added / Removed (classic and block-based carts)
* Cart Viewed, Checkout Started
* Product Clicked, Coupon Applied / Removed, Payment Info Entered
* Works without jQuery — block themes fully supported

**Marketing Attribution Engine**

* Captures UTM parameters and ad click IDs (gclid, fbclid, ttclid, msclkid, li_fat_id)
* Server-side first-party cookies bypass Safari ITP 24-hour restriction
* First-touch and last-touch attribution persisted to every order
* Days-to-conversion and session count tracking
* Falls back to WooCommerce 8.5+ native attribution when cookies are unavailable
* Attribution data included in all PostHog order events

**Identity Stitching**

* Reads PostHog JS SDK cookie server-side for seamless funnel connection
* Browser `posthog.identify()` for logged-in users
* Server-side `$identify` with `$anon_distinct_id` merges anonymous and known profiles
* PostHog funnels work end-to-end: Landing Page → Checkout Started → Order Completed

**LTV Person Enrichment**

* `total_orders`, `lifetime_value`, `avg_order_value`, `last_order_date` updated on every purchase
* `first_order_date`, `acquisition_source`, `acquisition_medium`, `acquisition_campaign` set once via `$set_once`
* Build PostHog cohorts like "Customers with LTV > $500 acquired from Google Ads"

**GDPR / Consent Management**

* Optional consent mode: starts PostHog opted-out with memory-only persistence
* Exposes `aphaOptIn()` / `aphaOptOut()` JavaScript functions
* Built-in support for CookieYes and Complianz consent management platforms

**WooCommerce Compatibility**

* HPOS (High-Performance Order Storage) compatible
* Cart and Checkout Blocks compatible
* Classic and block checkout flows supported
* Reverse proxy support for first-party tracking domains

= Requirements =

* WordPress 5.8+
* WooCommerce 7.0+
* PHP 7.4+
* A PostHog account (free tier available at posthog.com)

== Installation ==

1. Upload the `ag-data-for-posthog` folder to `/wp-content/plugins/`
2. Activate the plugin through the Plugins menu in WordPress
3. Go to WooCommerce > Settings > AG Data
4. Enter your PostHog project API key (starts with `phc_`)
5. Select your PostHog region (US or EU)
6. Optionally configure a reverse proxy URL for first-party tracking
7. Done! Events will start flowing to PostHog immediately.

== Frequently Asked Questions ==

= Where do I find my PostHog API key? =

Log in to PostHog, go to Project Settings, and copy the Project API Key. It starts with `phc_`.

= Does AG Data work with PostHog Cloud and self-hosted? =

Yes. Select US or EU for PostHog Cloud, or enter your self-hosted URL in the Custom Proxy URL field.

= Will this slow down my site? =

No. Server-side events use non-blocking HTTP calls. The frontend tracker is a lightweight script (~5KB) with no jQuery dependency. Attribution cookies are set server-side with minimal overhead.

= Does AG Data work with Safari ITP? =

Yes. Unlike JavaScript-set cookies (which Safari caps at 24 hours for URLs with tracking parameters), AG Data uses server-side `setcookie()` calls. These are treated as first-party cookies and persist for the full configured duration.

= How does attribution work? =

AG Data captures UTM parameters and ad click IDs (gclid, fbclid, ttclid, msclkid, li_fat_id) using server-side first-party cookies. First-touch and last-touch attribution data is persisted to every order and sent to PostHog, so you can analyze your full marketing funnel.

= Does AG Data support WooCommerce Blocks checkout? =

Yes. Both classic (shortcode) and block-based checkout flows are fully supported for identity persistence and event tracking.

== External services ==

This plugin connects to PostHog, a third-party product analytics service, to send your store's analytics and e-commerce event data. This connection is required for the plugin to work — its entire purpose is to record analytics in PostHog. No data is sent until you enter a PostHog Project API key in the plugin settings.

What PostHog is used for:

* Receiving server-side e-commerce events (Order Completed, Order Refunded, Order Status Changed).
* Receiving frontend browsing events (Product Viewed, Cart Viewed, Checkout Started, and similar) via the PostHog JavaScript SDK, which is loaded on your site's pages from your configured PostHog host.
* Storing person profiles enriched with order/LTV data and marketing attribution data.

What data is sent, and when:

* While a visitor browses your store, the PostHog JavaScript SDK captures pageviews and browsing events. This includes page URLs, referrer, UTM parameters, ad click IDs (gclid, fbclid, ttclid, msclkid, li_fat_id), and a PostHog-generated anonymous identifier.
* When an order is placed, refunded, or changes status, the plugin sends order data from your server — order ID, totals, currency, line items, payment and shipping method, and billing/shipping country. For logged-in users, a WordPress-based identifier and the customer email may also be sent so anonymous and known profiles can be merged.
* Requests are sent to the PostHog host you configure in the settings (PostHog US Cloud, PostHog EU Cloud, or your own self-hosted/proxy URL).

Service provider: PostHog Inc.
Terms of Service: https://posthog.com/terms
Privacy Policy: https://posthog.com/privacy

== Changelog ==

= 1.5.3 =
* Fix: Adds app_source=wordpress to server-side Order Completed attribution

= 1.5.2 =
* Fix: Escapes PostHog JavaScript property names and $pageview in the inline bootstrap snippet

= 1.5.1 =
* New: Adds a stable funnel_session_id across WordPress pageview, checkout, and server-side order events
* New: Adds funnel_key, host, source_host, source_page, and URL properties for cleaner PostHog CRO reporting
* Fix: Captures $pageview manually after registering funnel properties so landing-page views can join to checkout/order events

= 1.4.0 =
* Renamed plugin to AG Data for PostHog
* Fix: Inline scripts now use wp_add_inline_script() for WordPress standards compliance

= 1.3.1 =
* Fix: Form identify race condition — added submit listener to catch email before Elementor/AJAX redirect
* Fix: Autofill safety net — input listener catches browser autofill without blur
* Fix: Reduced form identify debounce from 400ms to 100ms
* Fix: Order Completed now fires identify before capture — events use email as distinct_id
* Fix: Upsell orders use billing email instead of random UUID fallback

= 1.3.0 =
* New: Element visibility tracking — fire PostHog events when visitors see key page elements
* New: Add CSS class `apha-track-view` to any element (works with Elementor, Block Editor, raw HTML)
* New: Custom event names via `data-apha-event` attribute
* New: Custom visibility threshold via `data-apha-threshold` attribute (default 50%)
* New: IntersectionObserver-based — no scroll listeners, great performance
* New: MutationObserver catches lazy-loaded/dynamic content
* New: "Element Visibility Tracking" toggle in WooCommerce > Settings > AG Data
* New: Consent-aware — re-initializes after opt-in when consent mode is active

= 1.2.0 =
* New: Form identification — identifies anonymous visitors in PostHog when they enter an email in any form (checkout, contact, signup)
* New: Supports WooCommerce classic checkout, block checkout, and generic forms (Elementor, CF7, WPForms, plain HTML)
* New: Auto-detects email and name fields on blur — captures even abandoned forms
* New: "Form Identification" toggle in WooCommerce > Settings > AG Data
* New: Respects person_profiles mode — uses setPersonProperties (always) or identify (identified_only)
* New: Consent-aware — re-initializes after opt-in when consent mode is active

= 1.1.0 =
* New: Marketing attribution engine with first-touch/last-touch UTM tracking
* New: Ad click ID capture (Google, Meta, TikTok, Microsoft, LinkedIn)
* New: Server-side first-party cookies (bypasses Safari ITP)
* New: LTV person enrichment (total_orders, lifetime_value, avg_order_value)
* New: Identity stitching — reads PostHog JS cookie server-side for seamless funnels
* New: Browser posthog.identify() for logged-in users
* New: Product Clicked, Coupon Applied/Removed, Payment Info Entered events
* New: Batch API endpoint support
* New: $set_once support for first_order_date, acquisition_source, created_at
* New: GDPR consent mode with CookieYes and Complianz integration
* New: WooCommerce 8.5+ native attribution fallback
* Fix: Race condition in Order Completed deduplication (TOCTOU)
* Fix: Replaced deprecated $create_alias with $identify + $anon_distinct_id
* Fix: Enabled capture_pageview for PostHog web analytics and session replay
* Fix: Standardized variant format (human-readable labels instead of IDs)
* Fix: jQuery dependency made optional for block themes
* Fix: False-positive product search detection
* Fix: Consolidated duplicate variation data loading (N+1 query)
* Improvement: Added payment_method, shipping_method, order_number, billing/shipping_country to Order Completed
* Improvement: Refund deduplication prevents duplicate Order Refunded events
* Improvement: Max products filter for data layer safety valve

= 1.0.0 =
* Initial release
* Server-side Order Completed, Order Refunded, Order Status Changed tracking
* Frontend Product Viewed, Product Added/Removed, Cart Viewed, Checkout Started
* Product List Viewed and Products Searched
* PostHog JS SDK integration with reverse proxy support
* WooCommerce HPOS and Blocks compatibility
* Identity management with cookie-based distinct IDs

== Upgrade Notice ==

= 1.4.0 =
Plugin renamed to AG Data for PostHog. All functionality and settings are preserved — no reconfiguration needed.

= 1.3.1 =
Fixes identity stitching — form identify now fires on submit (not just blur), Order Completed events use email as distinct_id, and upsell orders are properly attributed.

= 1.3.0 =
New element visibility tracking lets you know who actually saw key content on your landing pages — not just who triggered a pageview. Add `apha-track-view` class to any element.

= 1.2.0 =
New form identification feature links anonymous visitors to PostHog profiles when they enter their email in any form. Works with all form builders and WooCommerce checkout flows.

= 1.1.0 =
Major update: marketing attribution engine, identity stitching fix for PostHog funnels, LTV enrichment, and consent management. Recommended for all users.
