=== TagToSale – Conversion Tracking & Marketing Pixels ===
Contributors: carpatodesign
Tags: conversion tracking, woocommerce, google ads, meta pixel, chatgpt
Requires at least: 6.6
Tested up to: 7.1
Requires PHP: 8.1
Stable tag: 1.0.7
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Conversion tracking for WooCommerce, Google Ads, Meta Pixel, GA4 and ChatGPT/OpenAI Ads, with consent-aware automatic events.

== Description ==

TagToSale helps WordPress sites and WooCommerce stores send useful browser conversion and analytics events without requiring the site owner to understand each vendor's JavaScript API.

The Free edition is a complete browser-tracking plugin. You can connect only the channels you actually use. There is no second master switch hidden elsewhere in the interface.

= Browser destinations =

* Meta Pixel
* Google Analytics 4 / Google tag
* Google Ads conversion tags
* Google Tag Manager
* TikTok Pixel
* OpenAI / ChatGPT Ads Pixel when enabled and available for the advertiser

= Recommended automatic events =

New installations can use a recommended automatic-tracking preset for:

* Page views
* Scroll depth at 50% and 90%
* Engaged time at 30 and 60 seconds while the page is visible
* Successful form submissions for supported form plugins
* Telephone, email and WhatsApp link intent
* Outbound links
* File downloads
* Site search
* 404 diagnostics

Engagement events are analytics-first. A scroll, timer or generic click is not automatically treated as a Lead or Purchase.

Confirmed form-success listeners are included for Contact Form 7, Elementor Forms, WPForms, Gravity Forms and Fluent Forms when their documented/public success events are available. A generic submit-button click is not treated as a confirmed Lead.

= WooCommerce =

When WooCommerce is active, TagToSale uses WooCommerce APIs to normalize ecommerce events and product data. The browser event layer includes product views, product lists, cart actions, checkout and paid Purchase events, plus analytics-oriented refunds.

Purchase IDs are stable per order so refreshing the order-confirmation page does not intentionally create a new conversion identity. Product identifiers can use SKU or WooCommerce IDs with optional prefix/suffix matching for catalogs.

Purchase value can use the paid order total or an administrator-selected mode that excludes shipping, tax or uses items after discounts.

TagToSale declares compatibility with WooCommerce HPOS and Cart/Checkout Blocks and avoids adding a jQuery dependency solely for tracking.

= Consent =

TagToSale uses a denied fallback by default and can automatically detect supported consent tools. Current adapters include:

* ConsentMagic
* Complianz
* CookieYes / WebToffee
* Cookiebot
* Real Cookie Banner
* WP Consent API
* Custom/manual integration

The lightweight TagToSale core can load before advertising consent, but configured vendor SDKs are kept unloaded until the required consent state permits them. Consent changes are re-evaluated in the browser without requiring a page refresh where the CMP exposes a usable runtime signal.

Google tag consent state is represented with the Consent Mode v2 fields used by TagToSale: analytics_storage, ad_storage, ad_user_data and ad_personalization.

= Conversion rules =

A no-code rule builder is included for page/URL rules, links, phone/email/WhatsApp, CSS selectors, confirmed Contact Form 7 success, scroll, time, downloads and outbound links. Developers can also call:

`do_action( 'tagtosale_track_lead', 'contact_form' );`

or use `window.tagToSaleTrack()` on the frontend after a real confirmed action.

= Privacy and performance defaults =

* Shared-cache HTML does not contain customer email, phone, server API secrets or a reusable static event ID.
* Query parameters are removed from event source URLs generated by the core event model.
* The Free edition does not create TagToSale's Pro external-ID or campaign-attribution storage.
* Advertising SDKs are loaded only for enabled destinations after the relevant consent state.
* No CarpatoDesign product-usage telemetry is added by TagToSale.
* Known crawler traffic and logged-in WordPress administrators can be excluded by default.
* Frontend adapters are dependency-light and TagToSale does not add jQuery just for tracking.

TagToSale is designed to respect consent signals; installing a plugin does not by itself guarantee compliance with any law. Site owners remain responsible for their consent notice, lawful basis, vendor configuration and privacy disclosures.

= TagToSale Pro =

TagToSale Pro is distributed separately and is not included in the WordPress.org Free ZIP. It can add licensed server-side and first-party measurement capabilities to the same channel cards, including:

An active Pro license also includes free initial configuration assistance for supported tracking channels and ongoing support for bugs and feature requests by email. This is a support service offered by CarpatoDesign; it is not required to use the Free plugin.

* Meta Conversions API
* TikTok Events API
* GA4 Measurement Protocol
* OpenAI Conversions API for supported events
* Shared browser/server event IDs for supported conversion pairs
* Persistent asynchronous queue, retries and server-delivery diagnostics
* Consent-aware advanced matching for supported server destinations
* Pseudonymous first-party external ID
* First/last-touch browser attribution capture
* WooCommerce new/returning and configurable value segments for supported server events
* Internal TagToSale tracking-quality score

Successful server queue payloads are cleared after provider acceptance; diagnostics retain status/event identifiers rather than exposing API secrets or raw contact fields.

Google Ads Enhanced Conversions is not represented as a fake generic server toggle. TagToSale 1.0 keeps Google Ads browser conversion tags and Consent Mode v2 support while newer authenticated Google Ads/Data Manager workflows are treated as a separate integration path.

Server-side delivery can improve measurement completeness, but it does not bypass consent and cannot guarantee attribution, lower advertising costs or more sales.

= Upgrade and licensing =

The Free plugin remains usable without a purchase. Inside TagToSale pages, administrators may open a local Free/Pro comparison. When requested, TagToSale can retrieve the product's public pricing catalog through Freemius so available released plans/site quantities can be shown before the administrator chooses a hosted checkout.

The separately distributed Pro edition uses Freemius for license entitlement, account management and Pro software updates. Existing Freemius install/license state is intentionally stored in WordPress/Freemius and survives normal plugin file updates.

== External services ==

TagToSale connects only to services that the site administrator explicitly configures. Browser vendor scripts are loaded only when the destination is enabled and the visitor consent state allows that destination.

= Meta =

When Meta is enabled, the browser may load `https://connect.facebook.net/en_US/fbevents.js` and send configured events to Meta. The Pro edition can optionally send server events to Meta Graph/Conversions API. Meta terms and privacy policies apply: https://www.facebook.com/legal/terms and https://www.facebook.com/privacy/policy/

= Google =

When Google Analytics, Google Ads or GTM is enabled, the browser may load resources from `https://www.googletagmanager.com`. The Pro edition can optionally send GA4 Measurement Protocol events to `https://www.google-analytics.com/mp/collect` or Google's region endpoint when selected. Google policies apply: https://policies.google.com/terms and https://policies.google.com/privacy

= TikTok =

When TikTok is enabled, the browser may load the TikTok Pixel from `https://analytics.tiktok.com`. The Pro edition can optionally send events to TikTok's Events API. TikTok terms/privacy apply: https://www.tiktok.com/legal/terms-of-service and https://www.tiktok.com/legal/privacy-policy

= OpenAI / ChatGPT Ads =

When OpenAI/ChatGPT Ads measurement is enabled, the browser may load the OpenAI measurement SDK from `https://bzrcdn.openai.com` and send measurement events to OpenAI. The Pro edition can optionally send supported server conversion events to OpenAI's conversion endpoint. OpenAI terms/privacy apply: https://openai.com/policies/terms-of-use/ and https://openai.com/policies/privacy-policy/

= Freemius =

When an administrator explicitly opens TagToSale's Pro comparison, the plugin can request public product plan/pricing information via Freemius. If the administrator connects/activates the Freemius SDK or installs Pro, Freemius can process account, site, subscription and license information required for licensing and updates, subject to the administrator's opt-in choices and Freemius configuration. Freemius terms/privacy: https://freemius.com/terms/ and https://freemius.com/privacy/

TagToSale's own tracking IDs and visitor conversion events are not sent to CarpatoDesign as product analytics.

== Installation ==

1. Upload/install TagToSale and activate it.
2. Open **TagToSale > Tracking**.
3. Enable a destination and add its public Pixel/Tag ID.
4. Review **Consent**. Automatic detection is recommended.
5. Use a private/incognito window and the destination's own diagnostics to confirm events.

WooCommerce stores are detected automatically.

== Frequently Asked Questions ==

= Do I need every tracking channel? =

No. Configure only the channels you use. Unconfigured channels are optional and are not treated as setup errors.

= Does TagToSale send a Lead when somebody only clicks Submit? =

No for supported form integrations. TagToSale listens for a successful form event where the form plugin exposes one. A button click can still be configured manually as a custom rule, but it should not be confused with a confirmed Lead.

= Why are scroll and engaged-time events enabled? =

They are useful engagement signals and are routed analytics-first by default. They are not automatically marked as advertising conversions.

= Does TagToSale support server-side tracking in Free? =

No. Free is a complete browser-tracking plugin. Server transports and related premium code are distributed separately in TagToSale Pro.

= Is TagToSale GDPR compliant? =

No plugin can make that blanket legal guarantee. TagToSale is designed to respect supported consent signals and uses a denied fallback by default. Your site's implementation, notices, lawful basis and vendor settings remain your responsibility.

= Can another pixel plugin run at the same time? =

Yes, but sending the same event to the same destination from two plugins can create duplicates. TagToSale Diagnostics warns about several common tracking integrations but never disables another plugin automatically.

= Does Pro guarantee better ad results? =

No. Server-side measurement and better matching can improve measurement completeness and signal quality, but campaign outcomes depend on many factors.

== Screenshots ==

1. TagToSale dashboard with setup readiness, connected channels, detected consent solution and recommended tracking configuration at a glance.

2. Configure tracking destinations from one screen, including Meta Pixel, Google Analytics 4, Google Ads, Google Tag Manager, TikTok Pixel and ChatGPT Ads measurement.

3. Automatic event tracking for scroll depth, engaged time, successful forms, phone, email and WhatsApp actions, outbound links, downloads and 404 pages, with ready-made presets for different website types.

4. Map important website actions to consistent conversion events and create no-code conversion rules for thank-you pages, successful forms, WhatsApp enquiries, phone contacts and custom actions.

5. WooCommerce tracking with an automatic ecommerce funnel for product views, cart actions, checkout, purchases and refunds, plus configurable catalog IDs and purchase value settings.

6. Consent-aware tracking with automatic detection of supported cookie consent platforms and privacy-first controls that delay advertising tracking until the required visitor consent is available.

7. Built-in diagnostics and Health Check help verify tracking destinations, WooCommerce, consent handling and possible duplicate tracking, with a Live Event Inspector for debugging events.

8. Connect supported consent tools and popular WordPress form plugins, with a developer hook available for custom confirmed lead integrations.

9. Advanced settings for administrator and crawler exclusions, Debug mode, tracking pause controls, uninstall behavior and privacy-focused defaults.

== Changelog ==

= 1.0.7 =
* Improved attribution-cookie input sanitization and validation.

= 1.0.6 =
* Improved attribution-cookie sanitization.
* Added translator context for license site counts.

For the complete changelog, see changelog.txt.

== Upgrade Notice ==

= 1.0.2 =
Improves debugging for administrators, automatic-event routing guidance, conversion-rule UX, the WordPress admin-menu icon and confirmed Lead tracking for Contact Form 7 non-AJAX fallback submissions.

= 1.0.1 =
Admin UI polish for clearer Automatic Events and WooCommerce funnel summaries. No tracking behavior or saved settings are changed.

= 1.0.0 =
Major UX and measurement-quality release. Existing 0.3.x channel IDs, conversion rules, consent settings and Freemius association are migrated/preserved.
