=== CapiFlow – Conversions API (CAPI) Tracking for WooCommerce ===
Contributors: capiflow
Tags: facebook pixel, conversions api, meta pixel, woocommerce, tracking
Requires at least: 6.0
Tested up to: 6.9
Requires PHP: 7.4
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Maximize ad attribution with server-side Meta Conversions API tracking for WooCommerce — bypass Safari ITP and ad blockers.

== Description ==

**CapiFlow** connects your WooCommerce store directly to the Meta Conversions API (CAPI) — sending accurate purchase data server-to-server, bypassing Safari ITP, Firefox ETP, and ad blockers that block the browser pixel.

= Why Server-Side Tracking? =

The Meta browser pixel is blocked by up to 40% of users (ad blockers, Safari ITP, VPNs). When the pixel fails, Meta cannot optimize your ad spend or attribute purchases — you lose campaign data and pay more for results.

CapiFlow solves this by sending purchase events directly from your WooCommerce server to Meta's Conversions API, regardless of what the user's browser blocks.

= Core Features (Free) =

* **Server-side CAPI tracking** — Purchase, InitiateCheckout, AddPaymentInfo, AddToCart, ViewContent, Search, PageView
* **Browser pixel deduplication** — Prevents double-counting with correct event_id matching
* **First-party proxy endpoint** — Serves browser pixel events via your own domain (ITP bypass)
* **PII hashing** — Server-side data SHA-256 hashed before CAPI transmission; browser Advanced Matching uses Meta Pixel SDK's built-in auto-hashing
* **Higher Event Match Quality** — fbc, fbp, external_id, IP, User Agent all included
* **Checkout validation** — Phone number format validation for data quality
* **Quality Score dashboard** — EMQ score display when data is available (scores fetched by optional Pro addon via Meta API)
* **Analytics dashboard widget** — See rescued revenue from server-side tracking
* **Abandoned cart awareness** — View cart abandonment summary in dashboard
* **Debug console** — View sent events, payloads, and Meta API responses
* **System health check** — Token validity, queue status, PHP extension checks
* **Custom code injection** — Insert GTM containers, analytics scripts, or chat widgets in header, footer, and checkout pages (admin-only, respects `unfiltered_html` capability on multisite)
* **HPOS compatible** — Full WooCommerce High-Performance Order Storage support

= Requirements =

* WordPress 6.0 or higher
* WooCommerce 7.0 or higher
* PHP 7.4 or higher
* OpenSSL PHP extension
* A Meta Business Manager account with a Pixel and System User Access Token

= External Services =

This plugin connects to the following third-party services:

**Meta (Facebook) Conversions API**

CapiFlow sends WooCommerce event data (purchases, page views, cart actions)
to the Meta Conversions API via the Meta Graph API endpoint:
`https://graph.facebook.com/`

This connection is made from your server to Meta's servers whenever a
configured tracking event occurs (e.g., a customer completes a purchase or
views a product). No data is sent until the store owner configures a valid
Pixel ID and Access Token in the plugin settings.

Data transmitted includes:

* Hashed email address (SHA-256)
* Hashed phone number (SHA-256)
* Hashed first and last name (SHA-256)
* Client IP address (server-to-server)
* Browser User Agent
* Meta Click ID (_fbc) and Browser ID (_fbp) cookies
* Order total and currency
* Event metadata (event name, event ID, timestamp)

All personal data is SHA-256 hashed before transmission and cannot be
reversed. This plugin does not store raw PII in its own database tables.

Meta Terms of Service: https://www.facebook.com/terms.php
Meta Privacy Policy: https://www.facebook.com/privacy/policy/
Meta Platform Terms: https://developers.facebook.com/terms/

**Meta Pixel JavaScript SDK**

On the browser side, this plugin loads the official Meta Pixel JavaScript
SDK from: `https://connect.facebook.net/en_US/fbevents.js`

This script is loaded on every frontend page when a Pixel ID is configured.
It enables browser-side event tracking and Advanced Matching. The SDK is
hosted and maintained by Meta. Loading this script is subject to:

Meta Terms of Service: https://www.facebook.com/terms.php
Meta Privacy Policy: https://www.facebook.com/privacy/policy/

= Privacy =

CapiFlow sends the following customer data to Meta's Conversions API:

* Hashed email address (SHA-256)
* Hashed phone number (SHA-256)
* Hashed first and last name (SHA-256)
* Client IP address (server-to-server)
* Browser User Agent
* Meta Click ID (_fbc) and Browser ID (_fbp) cookies
* Order total and currency

For server-side CAPI events, all personal data is SHA-256 hashed before transmission. For browser-side events, the Meta Pixel SDK handles hashing automatically using its built-in Advanced Matching. This plugin does not store raw PII. See Meta's privacy policy: https://www.facebook.com/privacy/policy/

= Cookies =

CapiFlow sets and reads the following cookies:

* `cs_uid` — A random unique visitor identifier generated by the plugin.
  Used as the external_id for Meta CAPI deduplication and cross-session
  tracking. Lifetime: 180 days. Contains no personal information.
* `_fbc` — Meta Click ID cookie. Originally set by Meta Pixel SDK when a
  user clicks a Facebook ad. CapiFlow reads and extends this cookie via
  HTTP headers to improve server-side attribution. Lifetime: 180 days.
* `_fbp` — Meta Browser ID cookie. Originally set by Meta Pixel SDK.
  CapiFlow reads and extends this cookie server-side. Lifetime: 180 days.

These cookies are first-party (set on your domain) and do not contain any
personally identifiable information.

= Data Storage =

CapiFlow creates the following custom database tables:

* `{prefix}_capiflow_events` — Stores queued and sent CAPI event payloads
  (event name, status, HTTP response code, hashed payload). Automatically
  purged after events are sent and aged out.
* `{prefix}_capiflow_analytics` — Stores daily aggregated analytics
  (event counts, revenue, source attribution). Used for the dashboard.
  Automatically purged based on retention settings.

Additionally, CapiFlow stores order-level metadata with the `_capiflow_`
prefix on WooCommerce orders (client IP, user agent, cookies, event IDs,
traffic source). This data is used for server-side CAPI event enrichment
and is removed on uninstall if "Keep Data" is not enabled.

Log files are stored in `wp-content/uploads/capiflow-logs/` with
`.htaccess` protection to prevent public access. Logs are automatically
cleaned during daily maintenance.

= Privacy & Consent =

By default, CapiFlow fires tracking events once configured with a valid
Pixel ID and Access Token. To enforce consent-based blocking, enable the
"Consent Enforcement" toggle in CapiFlow Settings and configure a
supported Consent Management Platform (CMP). When enabled, CapiFlow will
respect tracking consent signals provided by the CMP for both browser
pixel and server-side CAPI events.

Supported CMPs: CookieYes, Complianz, CookieBot, GDPR Cookie Consent.
Custom integration is also available via the `capiflow_has_tracking_consent` filter.

If no supported CMP or custom consent hook is configured, tracking events
will continue to fire normally. Install and configure a compatible consent
solution to enforce consent-based blocking.

Store owners are responsible for installing and configuring a lawful
consent mechanism where required by applicable privacy regulations.

As a plugin developer, our role is to provide privacy-aware controls,
clear disclosures, and integration points for consent management.
Store owners remain responsible for their own legal compliance
and CMP configuration.

== Installation ==

1. Upload the `capiflow` folder to the `/wp-content/plugins/` directory, or install directly from the WordPress plugins screen.
2. Activate the plugin through the **Plugins** menu.
3. After activation, you will be redirected to the setup wizard.
4. Enter your **Meta Pixel ID** and **Access Token** from Meta Events Manager.
5. Click **Test Connection** to verify the setup.
6. You are live! Check **CapiFlow > Dashboard** to monitor events.

= Getting an Access Token =

1. Go to [Meta Events Manager](https://www.facebook.com/events_manager2/)
2. Select your Pixel → Settings → Conversions API
3. Click **Generate Access Token** or set up a System User with `ads_management` permission
4. Copy the token and paste it into CapiFlow → Settings → Pixel Settings

== Frequently Asked Questions ==

= Does this replace the Meta browser pixel? =

No. CapiFlow works **alongside** the Meta browser pixel. The browser pixel fires first; CapiFlow deduplicates the server-side event using the same `event_id`. This is the recommended "redundant" approach by Meta.

= Will this cause duplicate events in Meta? =

No. CapiFlow uses event deduplication via matching `event_id` values. Meta will automatically deduplicate when both browser and server events share the same event_id.

= How does this plugin handle privacy? =

CapiFlow hashes all personal data (email, phone, name) with SHA-256 before sending to Meta. CapiFlow also provides a Consent Enforcement toggle in Settings that respects consent signals from supported CMPs (CookieYes, Complianz, CookieBot) for both browser and server-side events. If no CMP is configured, events continue normally. Privacy policy content is added to your WordPress Privacy Policy page automatically. Store owners are responsible for ensuring their site meets applicable privacy regulations.

= Which WooCommerce order storage does this support? =

Both. CapiFlow supports traditional posts-based orders and WooCommerce High-Performance Order Storage (HPOS / Custom Order Tables).

= Does this work with my payment gateway? =

Yes. CapiFlow hooks into WooCommerce's standard order status transitions (`processing`, `completed`). It works with bKash, SSLCommerz, Stripe, PayPal, Cash on Delivery, and all other gateways.

= Do I need to modify any theme files? =

No. CapiFlow is a standalone plugin — no theme file modifications needed.

== Screenshots ==

1. **Analytics Dashboard** — Revenue rescued from server-side tracking
2. **Settings Page** — Pixel ID, Access Token, and event configuration
3. **System Health** — Real-time connection status and EMQ score
4. **Order Columns** — CAPI sync status and risk score per order
5. **Debug Console** — Event log with Meta API responses

== Changelog ==

= 1.0.0 — 2026-05-01 =

* Initial public release
* Server-side Purchase event tracking via Meta Conversions API
* Full WooCommerce HPOS compatibility
* First-party proxy for browser events (ITP bypass)
* SHA-256 PII hashing for all customer data
* Phone number checkout validation
* Analytics dashboard with rescued revenue metrics
* Setup wizard for first-time configuration
* Debug console for event inspection
* System health monitoring with Meta API connection test

== Upgrade Notice ==

= 1.0.0 =
Initial public release. No upgrade path needed.
