=== Pixlint – Multi-Pixel & Conversions API for WooCommerce ===
Contributors:      wpspire
Tags:              woocommerce, conversions api, meta pixel, ga4, pixel tracking
Tested up to:      7.1
Requires at least: 6.1
Requires PHP:      7.4
Stable tag:        1.3.0
License:           GPL-2.0-or-later
License URI:       https://www.gnu.org/licenses/gpl-2.0.html

All-in-one WooCommerce pixel tracking. Meta Conversions API (CAPI), GA4 Measurement Protocol, TikTok & Pinterest with auto-deduplication.

== Description ==

**Pixlint** is the most modern, lightweight, and powerful conversion tracking and pixel management plugin for WooCommerce and WordPress. Connect your **Meta (Facebook) Pixel** and **Google Analytics 4 (GA4)** (plus **TikTok Pixel**, **Pinterest Tag**, and **Google Ads** in Pro) with built-in server-side **Conversions API (CAPI)** and zero coding required.

In the post-iOS 14.5+ era, browser ad-blockers and privacy restrictions cause standard browser pixels to lose 20%–40% of conversion signals. Pixlint solves this with **Dual-Channel Tracking**: firing client-side browser tags while simultaneously sending robust, server-to-server CAPI events with **automatic deduplication** and **SHA-256 Advanced Matching**.

For documentation, tutorials, and support, visit the [official website](https://pixlint.wpspire.com/) or read our [Documentation Guides](https://pixlint.wpspire.com/docs/getting-started/quick-start/).

---

= 🌟 What Makes Pixlint Different? =

* **Dual-Channel Browser & Server-Side (CAPI) Tracking:** Maximize Event Match Quality (EMQ) and recover lost conversion signals without double-counting.
* **Automatic Event Deduplication:** Shares a synchronous `event_id` between browser pixels and server APIs so ad networks recognize and deduplicate identical events.
* **Zero Site Speed Impact:** All server-side CAPI requests are dispatched asynchronously and non-blocking — zero delay for shoppers during checkout.
* **Modern React Dashboard:** Clean, intuitive admin interface with built-in deep-links to platform setup guides.
* **100% HPOS & Block Checkout Compatible:** Fully compatible with WooCommerce High-Performance Order Storage and modern Block/Cart checkout flows.
* **Advanced User Privacy & Role Exclusions:** Automatically exclude Administrators, Shop Managers, or specific user roles from tracking to keep your analytics data pristine.

= 🆓 Pixlint Free — Core Features =

The Free version of Pixlint includes everything small to medium WooCommerce stores need for enterprise-grade tracking:

* **2 Active Pixel Slots:** Run up to 2 active pixels simultaneously (e.g., 1 Meta Pixel + 1 GA4 Stream).
* **Meta (Facebook) Pixel & Conversions API (CAPI):**
  * Full browser pixel tracking (`fbevents.js`) with `<noscript>` fallback.
  * Server-side Conversions API (CAPI) via Meta Graph API v20.0.
  * SHA-256 hashed customer Advanced Matching (Email, Phone, Name, City, State, Postcode, Country).
  * First-party `fbp` and `fbc` (from `fbclid` query params) cookie extraction for maximum ad attribution.
  * Test Event Code support for real-time verification in Meta Events Manager.
* **Google Analytics 4 (GA4) & Measurement Protocol:**
  * Client-side Google Tag (`gtag.js`) integration.
  * Server-side Measurement Protocol support for purchase tracking.
  * Full GA4 e-commerce parameters (`transaction_id`, `value`, `currency`, `items`, `item_id`, `item_name`).
  * GA4 Debug Mode toggle for live validation in GA4 DebugView.
* **Standard WooCommerce Events:**
  * **PageView / page_view**: Fires across all public pages.
  * **ViewContent / view_item**: Fires on single product pages with complete item parameters and configurable tax calculation (WooCommerce default, include tax, or exclude tax).
  * **ViewCategory / view_item_list**: Fires on product category and taxonomy archive pages.
  * **Search / view_search_results**: Fires on search results pages capturing search queries.
  * **AddToCart / add_to_cart**: Fires when products are added to the cart (single product & AJAX buttons) with configurable price tax options (WooCommerce default, include tax, or exclude tax).
  * **InitiateCheckout / begin_checkout**: Fires on checkout page load with configurable cart value modifiers (Total, Subtotal, Subtotal + Tax, or Subtotal + Shipping).
  * **Purchase / purchase**: Fires on order completion (Thank You page) with full line items and configurable order value modifiers (Total, Subtotal, Subtotal + Tax, or Subtotal + Shipping).
* **Lead & Engagement Event Tracking:**
  * **Contact Event**: Automatically tracks phone (`tel:`) and email (`mailto:`) link clicks.
  * **Lead Event**: Automatic form submission detection for Contact Form 7, WPForms, Mailchimp for WordPress (MC4WP), and MailPoet.
* **Pixel Page Visibility & Routing:** Include or exclude pixels based on specific URLs, post types, or taxonomies.
* **User Role Exclusions:** Prevent visits from Admins, Editors, Authors, and Shop Managers from skewing analytics.

= 🔥 Pixlint Pro — Premium Features =

Take your store's tracking and multi-channel ad attribution to the next level with **Pixlint Pro**:

* **Unlimited Multi-Pixel Management:** Connect unlimited pixels across Meta, TikTok, Google Ads, GA4, Pinterest, and niche ad channels.
* **Pinterest Tag & Conversions API (CAPI v5):**
  * Full browser Tag and server-side CAPI v5 integration.
  * Supported events: `PageVisit`, `ViewCategory`, `Search`, `AddToCart`, `ViewCart`, `InitiateCheckout`, `AddPaymentInfo`, `Checkout`, `AddToWishlist`, `RemoveFromCart`, `Refund`, `Signup`, and `Lead`.
  * First-party `_epik` click ID capture and automatic SHA-256 hashed customer data matching.
  * Server-side refund tracking for both partial line-item and full-order refunds.
  * Test Mode switch for validating signals in Pinterest Test Events tool.
* **TikTok Pixel & Events API (CAPI):**
  * Client-side pixel tracking with server-side TikTok Events API (CAPI).
  * Supported events: `PageView`, `ViewContent`, `AddToCart`, `InitiateCheckout`, `PlaceAnOrder`, `RemoveFromCart`, `AddPaymentInfo`, `Search`, `Contact`, `Lead`, and `CompleteRegistration`.
  * First-party `ttclid` capture and SHA-256 customer matching.
  * Built-in TikTok Test Event Code support.
* **Google Ads Enhanced Conversion Tracking:**
  * Map dedicated Google Ads Conversion Labels for Purchase, Add to Cart, Begin Checkout, View Item, View Item List, Search, Contact, Lead, and Complete Registration.
* **Advanced Ecommerce & User Lifecycle Events (Pro):**
  * **RemoveFromCart**: Tracks when products are removed from the cart (Page & AJAX).
  * **ViewCart**: Tracks shopping cart page views.
  * **AddPaymentInfo**: Tracks when payment methods are entered or selected.
  * **AddToWishlist**: Tracks wishlist additions (supports YITH and TI WooCommerce Wishlist).
  * **CompleteRegistration**: Tracks user registration completions (`sign_up`).
* **Server-Side Refund Tracking:**
  * Automatically trigger server-to-server CAPI refund events whenever orders are refunded (partial or full) in WooCommerce Admin.
* **Order Status Change Purchase Tracking:**
  * Fire CAPI purchase events when order status transitions (e.g. Pending to Processing or Completed), capturing phone and off-site orders.
* **Delayed ViewContent Tracking:**
  * Configure delay intervals (e.g. 5 seconds) before firing ViewContent to measure true user engagement and filter out bounce traffic.
* **1-Click Automatic Updates & Priority Support:**
  * Instant 1-click updates from WP Admin and dedicated developer support.

👉 Learn more and upgrade at [Pixlint Pro](https://pixlint.wpspire.com/)!

---

== Third-Party Services ==

This plugin connects to external third-party services to transmit pixel tracking and conversion analytics data based on your configured pixels:

= Meta (Facebook) =
* Loads Meta Pixel JavaScript from `https://connect.facebook.net/en_US/fbevents.js`.
* Sends server-side conversion events via the Meta Conversions API to `https://graph.facebook.com/`.
* Renders `<noscript>` fallback image from `https://www.facebook.com/tr`.
* [Meta Terms of Service](https://www.facebook.com/terms.php) | [Meta Privacy Policy](https://www.facebook.com/privacy/policy/)

= Google Analytics 4 & Google Ads =
* Loads Google Tag script from `https://www.googletagmanager.com/gtag/js`.
* Transmits server-side measurement events to `https://www.google-analytics.com/mp/collect`.
* [Google Terms of Service](https://policies.google.com/terms) | [Google Privacy Policy](https://policies.google.com/privacy)

= TikTok (Pro Add-on) =
* Loads TikTok Pixel SDK from `https://analytics.tiktok.com/i18n/pixel/events.js`.
* Sends server-side conversion events to `https://business-api.tiktok.com/open_api/v1.3/event/track/`.
* [TikTok Commercial Terms](https://ads.tiktok.com/i18n/official/policy/terms) | [TikTok Privacy Policy](https://www.tiktok.com/legal/page/row/privacy-policy/en)

= Pinterest (Pro Add-on) =
* Loads Pinterest Tag SDK from `https://s.pinimg.com/ct/core.js`.
* Transmits server-side conversion events via Pinterest Conversions API v5 to `https://api.pinterest.com/v5/ad_accounts/`.
* Renders `<noscript>` fallback image from `https://ct.pinterest.com/v3/`.
* [Pinterest Business Terms](https://business.pinterest.com/terms/) | [Pinterest Privacy Policy](https://policy.pinterest.com/en/privacy-policy)

---

== Installation ==

1. Log in to your WordPress admin panel.
2. Navigate to **Plugins** → **Add New Plugin**.
3. Search for **Pixlint** and click **Install Now**, then **Activate**.
4. Navigate to **Pixlint** in your WordPress sidebar menu.
5. Click **Add Pixel** and enter your Meta Pixel ID, Facebook CAPI Access Token, or GA4 Measurement ID.
6. Click **Save Pixel** and your store is immediately protected with dual-channel tracking!

---

== Frequently Asked Questions ==

= Does Pixlint require WooCommerce to work? =
No. While WooCommerce is required for e-commerce tracking (like ViewContent, AddToCart, and Purchase), you can install Pixlint on any standard WordPress site to track general PageView events, form submissions (Lead), and email/phone clicks (Contact).

= Is the Meta Conversions API (CAPI) free to use? =
Yes! Meta Conversions API is a free feature provided by Meta. You only need your Pixel ID and an Access Token generated from Meta Events Manager.

= How does Pixlint prevent duplicate events? =
Pixlint automatically attaches a unique `event_id` to both the browser tag and the server-side CAPI request for every action. When Meta or GA4 receives both signals, they automatically deduplicate them into a single accurate conversion.

= Will server-side tracking slow down my checkout? =
No. All server-side requests (Meta CAPI, GA4 Measurement Protocol, Pinterest CAPI, TikTok Events API) are executed asynchronously and non-blocking using `wp_remote_post( ..., array( 'blocking' => false ) )`. They have zero impact on page load speed or customer checkout times.

= Does Pixlint support WooCommerce HPOS (High-Performance Order Storage)? =
Yes. Pixlint is fully declared and tested compatible with WooCommerce HPOS and custom order tables.

= Does Pixlint work with caching plugins? =
Yes! Pixlint outputs its tracking code dynamically and handles AJAX events cleanly, ensuring complete compatibility with WP Rocket, LiteSpeed Cache, W3 Total Cache, Cloudflare, and server-level caching.

= Where can I find my credentials? =
Each field in the Pixlint Pixel Editor contains a direct **"Where to find?"** or **"How to generate?"** link that opens our step-by-step documentation guide for that specific platform.

---

== Screenshots ==

1. Pixel Management dashboard – view, manage, search, and toggle status for all your connected pixels across Meta, GA4, TikTok, Google Ads, and Pinterest.
2. Meta (Facebook) Pixel & CAPI Configuration – configure Pixel ID, Conversions API Access Token, Test Event Code, and granular Page Visibility rules.
3. Google Analytics 4 (GA4) Configuration – set up GA4 Measurement ID, Measurement Protocol API Secret for server-side purchase tracking, and Debug Mode.
4. TikTok Pixel & Events API Configuration – manage TikTok Pixel ID, Events API (CAPI) Access Token, Test Event Code, and visibility targeting.
5. Google Ads Conversion Tracking – map unique Google Ads Conversion Labels for Purchase, Add to Cart, Begin Checkout, Lead, and custom ecommerce actions.
6. Pinterest Tag & CAPI Configuration – connect Pinterest Tag, Conversions API v5 Access Token, Ad Account ID, and Test Mode.
7. Events Tracking & Multi-Pixel Routing – manage and toggle 17 standard & ecommerce events with per-pixel routing, delay timers, and real-time configuration health status.
8. Global Pixel Settings – customize user role exclusions, tracked parameters, and platform-specific options like Advanced Matching, 1st-party cookies, and noscript fallbacks.

---

== Changelog ==

= 1.3.0 =
* Feature: Add customizable product price tax calculation options (WooCommerce default, always include tax, always exclude tax) for ViewContent and AddToCart events.
* Feature: Add flexible cart and order value calculation modifiers (Total, Subtotal, Subtotal + Tax, Subtotal + Shipping) for Initiate Checkout and Purchase events.
* Enhance: Centralize price and event value calculation engine across all platforms under Event_Helper.
* Enhance: Include quantity parameter in GA4 view_item event for standard analytics compliance.
* Enhance: Standardize GA4 initiate_checkout line item pricing to respect configured tax options.
* Tweak: Confirm compatibility with WordPress 7.1 and WooCommerce 11.x.

= 1.2.1 =
* Feature: Add contextual documentation and setup guide links in the Pixel Configuration editor for all supported platforms.
* Enhance: Add "Where to find?" and "How to generate?" deep-links for Pixel IDs, CAPI Access Tokens, and Test Event Codes.
* Fix: Sanitize frontend script dependency arrays to prevent duplicate script enqueues.
* Tweak: Enhance visual hierarchy and link contrast across the admin configuration settings.

= 1.2.0 =
* Feature: Add Contact event tracking for phone (tel:) and email (mailto:) link clicks.
* Feature: Add Lead event tracking with automatic detection for Contact Form 7, WPForms, Mailchimp for WordPress (MC4WP), and MailPoet.
* Feature: Implement synchronous dual-channel event_id deduplication between browser pixels and server-side Conversions API (CAPI).
* Enhance: Highlight key terms and supported integrations with brand accent styling in the admin event cards.

= 1.1.0 =
* Feature: Enhance Meta Advanced Matching to extract customer billing data (email, phone, address) directly from WooCommerce orders.
* Feature: Add automatic CAPI fbc cookie fallback from URL query parameters (fbclid) and HTTP referrers.
* Feature: Add support for Gender (ge) and Date of Birth (db) customer match keys in Meta CAPI.
* Fix: Improve WooCommerce AJAX Add-to-Cart event deduplication and session persistence across HTTP requests.
* Fix: Ensure strict script dependency ordering so base pixel scripts load before event execution snippets.
* Fix: Add runtime WC_Order_Item_Product type checks and namespace safety in WooCommerce order loops.
* Tweak: Enhance frontend script enqueuing using wp_add_inline_script for WordPress guidelines compliance.
* Tweak: Optimize single product page AJAX detection and product ID resolution for custom buttons.

= 1.0.2 =
* Tweak: Support AJAX add to cart on single product pages.
* Tweak: Refactor WooCommerce add-to-cart JavaScript template generation to an OOP-driven architecture.

= 1.0.1 =
* Fix: Add WooCommerce Block Checkout compatibility for purchase tracking.
* Fix: Track variation IDs instead of parent product IDs in WooCommerce events (AddToCart, Purchase, etc.) and map parent IDs to item_group_id in GA4 events.
* Fix: Resolve correct page URL during AJAX and REST API requests (instead of reporting admin-ajax.php).

= 1.0.0 =
* Initial public release.

