=== Track Combo — Conversions API for WooCommerce ===
Contributors: trackcombo, lucaswhiather
Tags: conversions api, capi, server-side tracking, woocommerce, ecommerce tracking
Requires at least: 6.3
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Send WooCommerce events (view, add-to-cart, purchase) to Meta CAPI, Google Ads, and TikTok through Track Combo — no extra pixels needed.

== Description ==

**Track Combo — Conversions API for WooCommerce** turns your store into a unified tracking source. One plugin, one tag, and every relevant event reaches Meta (Facebook/Instagram), Google Ads, TikTok, Pinterest, Kwai and any destination you configure in your Track Combo workspace — both from the browser and from the server via the WooCommerce Webhook.

Instead of juggling multiple pixels, conflicting event IDs, and broken deduplication after the iOS 14 / browser tracking updates, Track Combo captures the event once on the storefront, enriches it with first-party data on the server, and fans it out to all destinations with proper **event_id** deduplication between client and server.

### What the plugin does

* Injects the Track Combo web tag in the storefront `<head>`.
* Exposes `window.tcWoo` with structured product, cart, order, and customer data so events do not depend on DOM scraping.
* Registers a native `WC_Webhook` that sends `order.updated` to the Track Combo backend when the order reaches the purchase status you choose.
* Deduplicates `purchase` between the client-side `complement_data` event and the server-side webhook using the order ID as `transaction_id`.
* Declares compatibility with **High-Performance Order Storage (HPOS)** and works with both classic shortcode and **Checkout Blocks** checkouts.

### Events sent

* `page_view`, `search`, `view_item_list`, `view_item`
* `add_to_cart`, `initiate_checkout`, `add_shipping_info`, `add_payment_info`
* `complement_data` (client-side on thank-you page, merged server-side)
* `purchase` (server-side via webhook — reliable even when the browser tab is closed)

### Why Conversions API

Tracking quality on WooCommerce stores dropped sharply after iOS 14.5 and the phase-out of third-party cookies. Conversions API (CAPI) is Meta's, Google's and TikTok's answer: send events directly from your server. Track Combo wraps all of them behind one integration.

### Why Track Combo instead of multiple plugins

* One plugin instead of one per ad network.
* One dedupe boundary handled by Track Combo — no `event_id` mismatches.
* No tag-manager containers to maintain.
* Full visibility of every event in the Track Combo dashboard.

You need a Track Combo account to use this plugin. Sign up at [trackcombo.com](https://trackcombo.com/).

== Installation ==

1. Upload the plugin to `/wp-content/plugins/track-combo-woocommerce/` or install it through the **Plugins** screen in WordPress.
2. Activate the plugin through the **Plugins** screen.
3. Go to **WooCommerce → Track Combo** and paste your API Key.
4. Pick the order status that should fire the purchase webhook (default: `processing`).
5. Save. The plugin validates the key, provisions the WooCommerce webhook, and starts sending events.

== Frequently Asked Questions ==

= Do I need a Track Combo account? =

Yes. The plugin is the WooCommerce connector for the Track Combo platform. You need an API key generated inside your Track Combo workspace.

= Does this replace Meta Pixel, Google Ads tag, TikTok Pixel? =

Yes. Once Track Combo is active and your destinations are configured inside the platform, you should remove the other pixels to avoid duplicate events.

= Is it compatible with HPOS (custom order tables)? =

Yes. The plugin declares `custom_order_tables` compatibility.

= Does it work with Checkout Blocks? =

Yes. The plugin exposes `cart_type: 'classic' | 'blocks'` to the code-event script so both flows are tracked correctly.

= Which order status fires the purchase event? =

You pick it in the settings. Default is `processing`. The server deduplicates so changing the status later (e.g., `processing → completed`) does not double-count.

= Where can I see the events? =

Inside your Track Combo workspace. You can also enable **Debug mode** in the settings to write verbose logs through the WooCommerce logger (source: `track-combo-woocommerce`).

= Is my data sent to third parties directly from my server? =

The plugin sends events only to the Track Combo backend. Track Combo then forwards them to the destinations you configured in your workspace (Meta, Google, TikTok, etc.).

= Does the plugin store personal data? =

The plugin itself does not persist orders or customer data. It forwards the data WooCommerce already holds to Track Combo for tracking purposes.

== External services ==

This plugin relies on Track Combo (https://trackcombo.com), the service operated by the plugin author, to deliver first-party event tracking and server-side conversion delivery to advertising platforms (Meta Conversions API, Google Ads, TikTok and others). It connects to the following Track Combo endpoints:

* **Configuration API** — `https://server.trackcombo.com/integrationwoocommerce`. Called only when the store owner saves the plugin settings in WordPress admin (validate the API key, persist the purchase status filter, register the store domain). Data sent: the API key (HTTP header), and the purchase status or store domain string when those are updated. No customer data is sent through this endpoint.

* **Web tag** — `https://track.track-combo.com/tag/{container_id}.js` (or your configured first-party CNAME, e.g. `https://tracks.yourstore.com/...`). Loaded on every storefront page view to enable client-side event tracking. The tag itself dispatches tracking events from the browser to the Track Combo events endpoint.

* **Order webhook** — a WooCommerce webhook registered by the plugin that POSTs the WooCommerce order payload to a URL on `server.trackcombo.com` whenever an order reaches the purchase status you configure in the plugin settings (default: "Processing"). This enables reliable server-side `purchase` events even when the customer closes the browser tab.

Track Combo terms of use: https://trackcombo.com/termos-de-uso/
Track Combo privacy policy: https://trackcombo.com/politica-de-privacidade/

== Changelog ==

= 1.0.0 =
* First public release.
* Full rewrite on a PSR-4 codebase.
* Tag injection with auto-detected domain, `window.tcWoo` payload, and HPOS / Checkout Blocks compatibility.
* Native `WC_Webhook` provisioning with idempotent reconciliation on settings save.
* i18n with English source and Brazilian Portuguese translation.

== Upgrade Notice ==

= 1.0.0 =
First public release. If you were using any pre-1.0 build of Track Combo for WooCommerce, deactivate it, install this release, and re-enter your API key.
