=== Admaxxer Analytics ===
Contributors: admaxxer
Tags: analytics, woocommerce, revenue, tracking, first-party
Requires at least: 5.8
Tested up to: 6.7
Requires PHP: 7.4
Stable tag: 1.3.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

First-party analytics and WooCommerce revenue attribution for Admaxxer — privacy-friendly, ad-blocker resistant.

== Description ==

**Admaxxer Analytics** connects your WordPress site to [Admaxxer](https://admaxxer.com) — the blended-profit dashboard and AI copilot for DTC brands.

This plugin:

* **Injects the Admaxxer pixel site-wide** with a single `defer`-loaded script.
* **Tracks pageviews, custom goals, and SPA navigation** out of the box.
* **Sends server-side WooCommerce order events** (purchase + completed) to Admaxxer over HMAC-signed webhooks, so revenue is attributed even when ad blockers or iOS privacy controls would block client-side events.
* **Supports cookieless tracking** for GDPR-compliant deployments that don't need a consent banner.
* **Works with self-hosted proxy origins** — route pixel traffic through your own domain (Cloudflare Worker, Vercel rewrite, Nginx) to bypass ad blockers entirely.

= Key features =

* Zero configuration beyond pasting your Website ID.
* Automatic `data-website-id` and `data-domain` injection.
* Cookieless mode (fingerprint-based) — no cookie consent required.
* SPA hash-mode support for themes using hash-based routing.
* Server-side WooCommerce order attribution with HMAC-SHA256 signatures.
* Visitor ID cookie bridging: the pixel visitor ID is passed to the webhook so conversions are matched to the correct traffic source in your Admaxxer dashboard.
* WooCommerce HPOS (High Performance Order Storage) compatible.
* Multisite compatible (options cleaned per-site on uninstall).
* Full i18n support — ships with a `.pot` file.

= Privacy =

Admaxxer is a first-party analytics tool. All data is stored under your workspace. In cookieless mode no persistent cookies are set. No data is shared with third parties. See [admaxxer.com/privacy](https://admaxxer.com/privacy).

== External Services ==

This plugin connects to the Admaxxer analytics platform (https://admaxxer.com)
to deliver first-party pixel tracking and server-side WooCommerce conversion
attribution.

**Pixel script (loaded in browser, on every front-end page):**

* Service: Admaxxer pixel CDN
* URL: `https://admaxxer.com/js/script.js?id={your_website_id}` (or your configured Proxy Origin)
* Data sent: page URL, referrer, user agent, anonymous visitor ID (cookie or fingerprint depending on cookieless mode), timestamp
* When: every front-end pageview after you save your Website ID in Settings
* No data is sent until you enter your Website ID

**Server-side WooCommerce events (sent from your server, only if WooCommerce HMAC Secret is configured):**

* Service: Admaxxer ingest webhook
* URL: `https://admaxxer.com/api/pixel/webhooks/woocommerce/{your_website_id}`
* Data sent: order ID, total, currency, customer email (for visitor stitching), Admaxxer visitor ID cookie value, line item count, units sold, subtotal/tax/discount/shipping breakdown, refund amount, customer lifetime order count and lifetime spend, payment gateway, order status (mapped to financial/fulfillment status), order source channel, customer tags, billing/shipping country, customer note, per-line item detail (SKU, vendor, quantity, price), and WooCommerce 8.5+ first-touch order attribution metadata.
* When: WooCommerce `woocommerce_thankyou` and `woocommerce_payment_complete` hooks fire
* Authentication: HMAC-SHA256 signature using your Webhook HMAC Secret

**Documentation, terms, and privacy:**

* Admaxxer service: https://admaxxer.com
* Terms of Service: https://admaxxer.com/terms
* Privacy Policy: https://admaxxer.com/privacy
* WordPress install guide: https://admaxxer.com/documentation/install/wordpress

By entering your Website ID and (optionally) your Webhook HMAC Secret in
Settings > Admaxxer, you authorize this plugin to transmit the data above to
Admaxxer. To stop all data transmission, clear the Website ID field or
deactivate the plugin.

== Installation ==

= From the WordPress Plugin Directory =

1. In your WordPress admin go to **Plugins > Add New**.
2. Search for "Admaxxer Analytics".
3. Click **Install Now**, then **Activate**.

= Manual installation =

1. Download the `.zip` file from the WordPress plugin directory.
2. In your WordPress admin go to **Plugins > Add New > Upload Plugin**.
3. Choose the `.zip` file and click **Install Now**, then **Activate**.

= Configuration =

1. Go to **Settings > Admaxxer**.
2. Paste your **Website ID** (found in your Admaxxer dashboard under Integrations > Pixel install).
3. *(Optional)* Enter a **Proxy Origin** if you want to route pixel traffic through your own domain.
4. *(Optional)* Enable **Cookieless Tracking** for GDPR compliance without a consent banner.
5. *(Optional)* Enable **SPA Hash Mode** if your theme uses hash-based routing.
6. *(WooCommerce only)* Paste your **Webhook HMAC Secret** from your Admaxxer dashboard > Integrations > WooCommerce > Connect (the "Final step: webhook setup" card) to enable server-side order attribution.
7. Click **Save Settings**.

That's it — the pixel is now active on every front-end page of your site.

== Frequently Asked Questions ==

= Where do I find my Website ID? =

Log in to [admaxxer.com](https://admaxxer.com), go to **Integrations > Pixel install**, and copy the Website ID. It starts with `admx_`.

= Do I need a WooCommerce HMAC secret to use the plugin? =

No. The pixel injection works without it. The HMAC secret is only required if you want server-side order attribution (recommended for WooCommerce stores because it can't be blocked by ad blockers).

= Is the plugin GDPR compliant? =

In cookieless mode, no persistent identifiers are stored in the browser. You can enable this in **Settings > Admaxxer > Enable Cookieless Tracking**. Review [admaxxer.com/privacy](https://admaxxer.com/privacy) and your own legal requirements.

= Does this plugin slow down my site? =

No. The pixel script is loaded with `defer`, which means it does not block page rendering. The server-side WooCommerce webhook fires asynchronously after the order is placed.

= Can I use a proxy to avoid ad blockers? =

Yes. Enter your proxy origin URL in **Settings > Admaxxer > Proxy Origin**. See the [Admaxxer proxy documentation](https://admaxxer.com/documentation/proxy/wordpress) for Cloudflare Worker, Vercel, Nginx, and other guides.

= Is this plugin compatible with WooCommerce High Performance Order Storage (HPOS)? =

Yes. The plugin declares HPOS compatibility and uses the WooCommerce order API rather than direct database queries.

= Does this work on WordPress Multisite? =

Yes. Each site in the network has its own settings. On plugin deletion, options are cleaned from every site.

= What PHP version is required? =

PHP 7.4 or higher. PHP 8.x is fully supported.

== Screenshots ==

1. Settings page under Settings > Admaxxer.
2. WooCommerce order note showing successful event dispatch.
3. Admaxxer dashboard showing attributed WooCommerce revenue.

== Changelog ==

= 1.3.0 =
* Deep WooCommerce order extraction (Triple-Whale "Sonar" parity): adds `customer_tags`, `billing_country`, `shipping_country`, `customer_note`, per-line `line_items_detail` (line_item_id, product_id, variant_id, sku, quantity, price_cents, total_discount_cents, vendor, name), and full WooCommerce 8.5+ `wc_attribution` (first-touch source/medium/campaign/device_type/session_count, etc.) — all forwarded to the Admaxxer ingest webhook.
* Vendor field uses the `pa_vendor` taxonomy attribute (or `vendor` fallback) so multi-vendor stores (Dokan, WC Vendors) get correct attribution per line item.
* Backward-compatible: every new field is wrapped in `method_exists()` / null guards; older WooCommerce versions degrade to empty strings rather than crashing.
* Pixel script is unchanged in this release — pair with the latest pixel for Sonar-style anonymous→identified visitor stitching at form-submit time (CAPI match rate ≈100%).

= 1.2.0 =
* Extended WooCommerce order extraction: line item count, units sold, subtotal/tax/discount/shipping breakdown, refund amount, customer lifetime order count + lifetime spend, payment gateway, Shopify-style financial and fulfillment status, source channel, gross sales — populates Triple-Whale-style dashboard tiles in Admaxxer (AOV, units sold, new-customer rate, gross-vs-net).
* Backward-compatible: every new field is wrapped in a `method_exists()` / null guard so older WooCommerce versions degrade gracefully (default 0 / null) rather than crashing.
* Maps WC status (`completed`, `processing`, `refunded`, `cancelled`, `failed`, ...) to Shopify-style `financial_status` (`paid`, `pending`, `refunded`, `partially_refunded`, `voided`, `failed`) so cross-platform dashboards render with a uniform vocabulary.

= 1.1.0 =
* Added `woocommerce_payment_complete` hook for reliable purchase tracking on redirect-gateway flows (PayPal, Stripe redirect) — catches paid orders even when the customer never reaches the thank-you page.
* Added atomic local idempotency guard via order meta (`_admx_capi_sent_{event_type}`) to prevent duplicate event POSTs when multiple WooCommerce hooks fire for the same order.
* Added explicit `== External Services ==` disclosure section to readme.txt.
* Bumped tested-up-to to WordPress 6.7.

= 1.0.0 =
* Initial release.
* Pixel injection via `wp_enqueue_scripts` with `defer` and `data-website-id` / `data-domain` attributes.
* Admin settings page (Website ID, Proxy Origin, Cookieless, SPA Hash Mode, WooCommerce HMAC Secret).
* WooCommerce server-side order attribution (`woocommerce_thankyou` and `woocommerce_order_status_completed`).
* HMAC-SHA256 signed webhooks.
* Visitor ID cookie bridging.
* Multisite uninstall cleanup.
* Full i18n with `.pot` file.
* WooCommerce HPOS compatibility declared.

== Upgrade Notice ==

= 1.3.0 =
Adds deep order extraction (customer tags, billing/shipping country, line-item detail with vendor/SKU, full WooCommerce 8.5+ attribution) so dashboards in Admaxxer get SKU-level creative attribution and first-touch source on every order. Backward-compatible.

= 1.2.0 =
Sends 17 new aggregate fields per WooCommerce order (line item count, units sold, subtotal/tax/discount/shipping breakdown, refund amount, customer lifetime stats, gateway, financial/fulfillment status). Required for full Triple-Whale-style dashboard tiles in Admaxxer. Backward-compatible.

= 1.1.0 =
Adds `woocommerce_payment_complete` hook so PayPal/Stripe redirect-abandonment orders are still tracked, and an atomic local dedup guard. Recommended for all WooCommerce stores.

= 1.0.0 =
Initial release — no upgrade steps required.

== Additional Notes ==

= Assets =

* `assets/icon-256x256.png` — **Add before submission**: 256×256 PNG plugin icon (use the Admaxxer logo on a white or transparent background).
* `assets/banner-772x250.png` — **Add before submission**: 772×250 PNG plugin directory banner.

These image assets are required by the WordPress plugin directory. They are not bundled in this repository. Add them to `assets/` before submitting to the WordPress.org plugin review team.

= Support =

* Documentation: [admaxxer.com/documentation/install/wordpress](https://admaxxer.com/documentation/install/wordpress)
* Support forum: [wordpress.org/support/plugin/admaxxer](https://wordpress.org/support/plugin/admaxxer)
* Issues: [admaxxer.com/contact](https://admaxxer.com/contact)
