=== PantoSource for WooCommerce ===
Contributors: pantosource
Tags: conversion tracking, attribution, server-side tracking, woocommerce, capi
Requires at least: 6.0
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 1.0.39
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Recover up to 60% more conversions. Connect your WooCommerce store to PantoSource for server-side ad attribution across Meta, Google, and TikTok.

== Description ==

**PantoSource for WooCommerce** connects your store to the [PantoSource](https://pantosource.com) AI-powered ad tracking platform. Every visit, add-to-cart, checkout, and purchase event is captured server-side and sent to PantoSource for enrichment and attribution — immune to ad blockers, iOS privacy restrictions, and browser cookie limitations.

PantoSource enriches your conversion data with first-party signals and pushes accurate attribution back to your ad platforms automatically, so their algorithms can optimize on real data and improve your ROAS.

**Why server-side tracking?**

Standard browser pixels miss up to 60% of conversions due to ad blockers, iOS 14.5+ restrictions, and cookie consent friction. Server-side tracking captures events directly from your server, ensuring near-complete conversion coverage and more reliable attribution.

**What this plugin does:**

* Sends WooCommerce events to PantoSource in real time via server-side API calls
* Tracks the full customer journey: page views, product views, product searches, sign-ups, logins, add-to-cart, checkout initiation, and completed purchases
* Passes enriched event data (order value, product details, customer signals) to the PantoSource platform
* Enables PantoSource to relay accurate conversion data to Meta (Facebook & Instagram), Google Ads, TikTok, and more via their respective Conversions APIs

**Key benefits:**

* Recover conversions that pixel-based tracking misses
* Feed ad platform algorithms with accurate, complete data
* Improve ROAS as optimization improves on real signals
* Lower CPA by cutting underperforming campaigns with confidence
* No coding required — configure with a single API key
* Live in under 5 minutes
* While active, outputs an HTML verification comment in the storefront `<head>` so PantoSource can confirm install during store setup

**Supported ad platforms (via PantoSource):**

* Meta (Facebook & Instagram) — Conversions API
* Google Ads — Enhanced Conversions
* TikTok — Events API

A free 14-day trial of PantoSource is available at [pantosource.com](https://pantosource.com/pricing). A PantoSource account and API key are required to use this plugin.

**Requirements:** WooCommerce must be installed and active. The plugin header declares `Requires Plugins: woocommerce`.

Disclaimer: This plugin is not affiliated with or endorsed by Automattic, WooCommerce, Meta, Google, or TikTok.

== Installation ==

= Prerequisites =

* WordPress 6.0 or higher
* WooCommerce plugin installed and activated
* A PantoSource account — [sign up free at alfa.pantosource.com](https://alfa.pantosource.com)

= Method 1: WordPress Admin Dashboard (Recommended) =

1. In your WordPress admin dashboard, go to **Plugins > Add New**
2. Search for **PantoSource for WooCommerce**
3. Click **Install Now**, then **Activate**

= Method 2: Manual Upload =

1. Download the plugin ZIP file
2. In your WordPress admin, go to **Plugins > Add New > Upload Plugin**
3. Choose the downloaded ZIP file and click **Install Now**
4. Click **Activate Plugin**

= Method 3: FTP Upload =

1. Download and extract the plugin ZIP file
2. Upload the `pantosource-for-woocommerce` folder to `/wp-content/plugins/` on your server
3. In your WordPress admin, go to **Plugins** and activate **PantoSource for WooCommerce**

= Configuration =

1. In your WordPress admin, navigate to **PantoSource** in the sidebar
2. Log in to your PantoSource account at [alfa.pantosource.com](https://pantosource.com) and copy your API key
3. Paste the API key into the field and click **Verify and Save**
4. A success message confirms your store is connected
5. Check your PantoSource dashboard to confirm events are flowing

= Notes =

* If you use a caching plugin (WP Rocket, WP Super Cache, NitroPack, etc.), clear your cache after installation
* The plugin begins tracking automatically once the API key is verified — no further setup is required
* The plugin does not start PHP sessions on the storefront, so full-page caching remains compatible for anonymous visitors

== Frequently Asked Questions ==

= Do I need a PantoSource account? =

Yes. This plugin requires a PantoSource account to function. You can start a free 14-day trial — you won't be charged until your trial ends, and you can cancel anytime before then.

= Which WooCommerce events are tracked? =

The plugin tracks the following standard WooCommerce events:

* Page View (including SPA route changes when enabled)
* View Product / Product List / Product Search
* View Cart
* Sign up / Login / Logout
* Customer profile update
* Add to Cart
* Initiate Checkout
* Add Payment Info
* Order Processed
* Purchase (Order Complete)
* Order Fulfilled (when order status becomes completed)
* Order Cancelled / Refund Created
* Add to Wishlist (YITH / TI plugins)

= Does this replace my existing ad pixels? =

PantoSource works alongside your existing browser pixels to provide supplemental server-side coverage. It does not remove or interfere with other tracking scripts you have installed.

= Is this compatible with cookie consent plugins? =

Yes. PantoSource integrates with the [WP Consent API](https://wordpress.org/plugins/wp-consent-api/) using the **marketing** consent category. When a compatible consent management plugin (Complianz, Cookiebot, CookieYes, etc.) is active, tracking and cookies are gated until the visitor accepts marketing cookies. If no consent management plugin is active, tracking runs by default (same behavior as other WP Consent API–compatible plugins). There is no merchant-configurable consent override in plugin settings. For regional compliance details, see PantoSource's [Privacy Policy](https://pantosource.com/privacy-policy), [GDPR documentation](https://pantosource.com/gdpr), and [DPA](https://pantosource.com/dpa).

= Which ad platforms does PantoSource support? =

PantoSource supports Meta (Facebook & Instagram), Google Ads and TikTok. Additional platforms are added regularly — see [pantosource.com](https://pantosource.com) for the current list.

= Will this slow down my store? =

No. All API calls to PantoSource are made asynchronously in the background and do not affect your store's page load time or customer experience.

= Where can I get support? =

Please use the [WordPress.org support forum](https://wordpress.org/support/plugin/pantosource-for-woocommerce/) for general questions, or contact PantoSource directly at [pantosource.com/contact](https://pantosource.com/contact).

== Screenshots ==

1. The PantoSource settings page in the WordPress admin — Settings tab for the PantoSource API key and consent, Advanced tab for diagnostics and other options.
2. Real-time event feed in the PantoSource dashboard showing WooCommerce events.
3. Attribution report in PantoSource showing which ads drove each purchase.
4. Ad platform connection screen — link your Meta, Google, and TikTok accounts to receive enriched conversion data.

== Changelog ==

= 1.0.39 =
* Improve event tracking reliability.

= 1.0.38 =
* Improve event tracking reliability.

= 1.0.37 =
* Improve event tracking reliability.

= 1.0.36 =
* Improve event tracking reliability.

= 1.0.35 =
* Improve event tracking reliability.

= 1.0.34 =
* Improve event tracking reliability.

= 1.0.33 =
* Improve event tracking reliability.

= 1.0.32 =
* Improve event tracking reliability.

= 1.0.31 =
* Improve event tracking reliability.

= 1.0.30 =
* Improve event tracking reliability.

= 1.0.29 =
* Improve event tracking reliability.

= 1.0.28 =
* Improve event tracking reliability.

= 1.0.27 =
* Improve event tracking reliability.

= 1.0.26 =
* Online-store channel filter: emit order lifecycle and purchase events only when `created_via` is `checkout` or `store-api` (extend via `pantosource_online_store_created_via` filter).
* Add `commerce.sales_channel` on order events (raw `created_via`).
* Background order snapshot export to PantoSource (Action Scheduler hourly incremental and daily full window) for store health reconciliation; optional `pantosource_portal_base_url` (default `https://app.pantosource.com`).

= 1.0.25 =
* Send the order payment status with each purchase, and a payment status update when an order is paid, fails, is cancelled or refunded.
* Do not send a purchase for failed orders on the thank-you page.

= 1.0.24 =
* Improve event tracking reliability.

= 1.0.23 =
* Improve event tracking reliability.

= 1.0.22 =
* Improve event tracking reliability.

= 1.0.21 =
* Improve event tracking reliability.

= 1.0.20 =
* Improve event tracking reliability.

= 1.0.19 =
* Improve event tracking reliability.

= 1.0.18 =
* Improve storefront event tracking reliability.

= 1.0.17 =
* Persist Meta/TikTok matching cookies (`_fbp`/`_fbc`/`_ttp`) on `pantosource_attr` with field-level union, and emit `marketing.cookies`
* Map `product.variant_id`, `name`, and `price` on browse/ATC; persist last client IP/UA/cookies on checkout order meta for hosted-payment purchases

= 1.0.16 =
* Emit `woocommerce_add_to_cart` only for explicit ATC channels: POST `add-to-cart`, `wc-ajax=add_to_cart`, Store API `cart/add-item`, or user document-navigation GET `?add-to-cart=` (no blanket POST / `wp_doing_ajax`)
* Include optional `plugin_version` on every event (`extensions.woocommerce.plugin_version` and `data.plugin_version`)

= 1.0.15 =
* Do not emit `woocommerce_add_to_cart` for prefetch/prerender or non-user GET `?add-to-cart=` (product-page related-product prefetches); strip those query params before WooCommerce adds to cart
* ATC emit requires a user channel: POST / `wc-ajax=add_to_cart` / Store API `cart/add-item` / user document navigation GET
* Frontend cart fast path (default off) matches POST Store API `cart/add-item` and `wc-ajax=add_to_cart` only (no `add-to-cart` URL substring)

= 1.0.14 =
* Send `document.referrer` from JS; do not treat AJAX `HTTP_REFERER` as page referrer when it equals the current URL (fixes self-referrers)
* Suppress `woocommerce_cart_item_quantity_changed` during add-to-cart requests (ATC watermark/2s dedupe remain source of truth)
* sessionStorage TTL dedupe for pageview / product_viewed across post-ATC reloads
* Sticky first-touch landing: never persist cart / checkout / order-received as session or attribution landing
* Fill `user.external_id` from logged-in WP/WC customer on frontend events
* PHP checkout pageview before `checkout_initiated`; JS skips duplicate checkout pageview; suppress `customer_updated` during checkout

= 1.0.13 =
* AJAX / non-storefront page URL prefers storefront HTTP referer over session landing (fixes home `/` on ATC, payment info, order processed)
* Treat `wp-login.php` as non-storefront; logout events use my-account / referer as page URL
* ATC emit only when cart line quantity increases (session watermark) in addition to 2s double-fire dedupe
* Suppress `woocommerce_customer_updated` for 60s after signup; emit `logged_in` after registration auto-auth if `wp_login` did not

= 1.0.12 =
* Hoist browser `current_url` into canonical `context.page.url` / `path` (AJAX root + same-host referer fallback); ignore Store API / admin-ajax URLs as landing
* Short 2s WC-session/transient dedupe for `woocommerce_add_to_cart` against Blocks/theme double-fires; payload `trigger_source: php_hook`
* Emit `woocommerce_checkout_order_processed` from Store API `woocommerce_store_api_checkout_order_processed` (Block checkout) in addition to classic hook
* Thank-you page: frontend `page_type` `order_received` via `isOrderReceived`

= 1.0.11 =
* Emit `add_payment_info` for Block / Store API checkout (`woocommerce_store_api_checkout_update_order_from_request`) in addition to classic `woocommerce_checkout_process`
* Optional frontend emit on payment method selection (classic + Blocks radios); shared WC session dedupe `pantosource_payment_info_sent`
* Emit `view_cart` from cart-page JS when the frontend tracker is on (covers Cart block where `woocommerce_before_cart` often never fires)
* Remove duplicate `product_list_viewed` MutationObserver path on the shop page

= 1.0.10 =
Directory listing update.

= 1.0.9 =
* Security: frontend rate-limit transient is now keyed on the server-observed IP only, preventing client-controlled keys from flooding transients or bypassing the limit
* Prefix all plugin transients with pantosource_ (dedupe, rate-limit, customer-updated) to avoid collisions with other plugins
* Rename the custom one-minute cron schedule to pantosource_minute (was the generic "minute") to avoid cron_schedules collisions; existing installs migrate automatically

= 1.0.8 =
* Plugin Check PHPCS: document cart quantity array sanitization after verified WooCommerce cart nonce

= 1.0.7 =
* Plugin Check PHPCS cleanup: remove unused POST JSON helper; verify WooCommerce cart nonce before reading cart quantities

= 1.0.6 =
* Plugin Check remediation: release packaging excludes dotfiles and dev markdown
* Input PHPCS compliance for cookies, cart POST detection, and AJAX JSON decode paths
* Remove manual load_plugin_textdomain() for WordPress.org auto-translation

= 1.0.5 =
* Declare compatibility with WooCommerce High-Performance Order Storage (HPOS)

= 1.0.4 =
* WordPress Plugin Review remediation: structured input sanitization for cookies, POST JSON, and order meta
* Replaced PHP sessions with consent-gated marketing cookies for session id and server landing URL (cache-friendly)
* Added Requires Plugins: woocommerce header and WooCommerce-guarded initialization
* Text domain aligned to pantosource-for-woocommerce; load_plugin_textdomain() on plugins_loaded
* Registered pantosource_session_id and pantosource_server_landing_url with WP Consent API

= 1.0.0 =
* Initial release
* Server-side event tracking for WooCommerce (Page View, View Product, Product Search, Sign Up, Login/Logout, Add to Cart, Initiate Checkout, Purchase)
* API key authentication with PantoSource
* Real-time event delivery to the PantoSource platform

== Upgrade Notice ==

= 1.0.18 =
Reliability improvements for storefront event tracking.

= 1.0.17 =
Meta/TikTok matching cookies persist across pageviews; checkout snapshot keeps browser IP for PayPal/Stripe purchases. Hard-refresh the storefront after install.

= 1.0.13 =
ATC line-qty suppress; AJAX page URLs prefer referer; quieter signup updates; login after register; cleaner logout URLs.

= 1.0.12 =
Correct page URLs on AJAX events; ATC double-fire dedupe; Block checkout order_processed; thank-you order_received page type.

= 1.0.11 =
Block checkout: add_payment_info via Store API; view_cart via cart-page JS; shop list-view dedupe.

= 1.0.10 =
Directory listing update.

= 1.0.9 =
Security hardening for the frontend rate limiter and pantosource_-prefixed transients.

= 1.0.8 =
Plugin Check PHPCS compliance for cart quantity detection.

= 1.0.7 =
Plugin Check PHPCS compliance for cart remove detection.

= 1.0.6 =
Plugin Check and WordPress.org packaging compliance update.

= 1.0.5 =
HPOS compatibility declaration for WooCommerce High-performance order storage.

= 1.0.4 =
Security and WordPress.org compliance update: input sanitization, no PHP sessions on storefront, Requires Plugins header.

= 1.0.0 =
Initial release of PantoSource for WooCommerce.

== External services ==

This plugin connects to PantoSource operated by Panto Martech LLC:

* **Event ingestion** — `https://events.pantosource.com` by default (POST `/events`); real-time WooCommerce tracking events with Bearer store API key. A custom base URL is kept.
* **Portal storefront API** — `https://app.pantosource.com` by default (`pantosource_portal_base_url`); background **order snapshot** uploads (order IDs, status, totals, channel, no personal data) for store health reconciliation. Requests use `Authorization: Bearer`, `X-Panto-Integration: woocommerce`, and `X-Panto-Integration-Version`.

See the [Privacy Policy](#privacy-policy) section below for data handling.

== Privacy Policy ==

This plugin transmits WooCommerce event data — including page URLs, product details, order values, and hashed customer signals — to the PantoSource platform operated by Panto Martech LLC.

Data is used solely for ad attribution and conversion tracking on behalf of the store owner. PantoSource does not sell personal data to third parties.

For full details, please review:

* [PantoSource Privacy Policy](https://pantosource.com/privacy-policy)
* [PantoSource GDPR Documentation](https://pantosource.com/gdpr)
* [Data Processing Agreement (DPA)](https://pantosource.com/dpa)
* [Sub-Processors](https://pantosource.com/sub-processors)
