=== Halfborg Pixel Tracking for WooCommerce ===
Contributors: alexhalfborg
Tags: woocommerce, conversion api, pixel, tracking, analytics
Requires at least: 5.0
Tested up to: 7.0
Requires PHP: 7.2
Requires Plugins: woocommerce
Stable tag: 1.1.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Sends WooCommerce order details to the Facebook Conversions API.

== Description ==

Halfborg Pixel Tracking for WooCommerce sends your store's purchase events directly to Facebook's Conversions API. This server-side tracking solution helps maintain accurate conversion tracking even when client-side tracking is blocked by ad blockers or browser privacy settings.

= Features =

* Sends purchase events to Facebook Conversions API
* Works with WooCommerce's High-Performance Order Storage (HPOS)
* Securely hashes customer data before sending to Facebook
* Easy setup with minimal configuration

= How It Works =

1. When a customer completes an order, the plugin captures the order details
2. Customer data is securely hashed using SHA-256
3. The purchase event is sent directly to Facebook's Conversions API
4. The event includes order value, currency, and attribution data

== Installation ==

1. Upload the plugin files to the `/wp-content/plugins/halfborg-pixel-tracking-for-woocommerce` directory, or install the plugin through the WordPress plugins screen directly.
2. Activate the plugin through the 'Plugins' screen in WordPress
3. Go to WooCommerce > Pixel Tracking to configure the plugin
4. Enter your Facebook Conversions API Access Token and Pixel ID

== Frequently Asked Questions ==

= Where do I find my Facebook Conversions API Access Token? =

You can generate an access token in Events Manager. Go to Events Manager > Data Sources > select your Pixel > Settings > Conversions API > Generate access token.

Facebook's official instructions: https://developers.facebook.com/docs/marketing-api/conversions-api/get-started/

= Where do I find my Facebook Pixel ID? =

Your Pixel ID can be found in Events Manager under Data Sources, next to your pixel name.

Facebook's official instructions: https://www.facebook.com/business/help/952192354843755

= Is this plugin compatible with WooCommerce HPOS? =

Yes, this plugin is fully compatible with WooCommerce's High-Performance Order Storage (HPOS) feature.

== Screenshots ==

1. Settings page

== External services ==

This plugin connects to Meta (Facebook) to send e-commerce tracking events. This is the core purpose of the plugin and it cannot function without it. Two separate Meta services are used.

**1. Meta Conversions API (server-side)**

The plugin sends conversion events from your server to the Meta Conversions API endpoint at `https://graph.facebook.com`. This is what allows conversions to be attributed to your Meta ad campaigns even when the browser pixel is blocked.

Events are sent when a visitor views a product (ViewContent), adds a product to the cart (AddToCart), begins checkout (InitiateCheckout), and completes an order (Purchase).

The data sent with these events is: the customer's email address, phone number, first and last name, city, state, postcode and country — each of which is irreversibly hashed with SHA-256 before it leaves your server — together with the order or product value, the currency, the product IDs, the number of items, an event ID used for deduplication, the page URL, and the visitor's IP address, browser user-agent and Meta browser cookies (`_fbc` and `_fbp`), which Meta requires in unhashed form for attribution.

Nothing is sent until you enter a Pixel ID and a Conversions API Access Token on the settings screen. If either is missing, no server-side event is sent.

**2. Meta Pixel (browser-side)**

When a Pixel ID is configured, the plugin loads Meta's tracking script `fbevents.js` from `https://connect.facebook.net` into your visitors' browsers, and the pixel reports page views and the events listed above to `https://www.facebook.com`. Each browser event carries the same event ID as its server-side counterpart so Meta can deduplicate the pair. A `<noscript>` image fallback to `https://www.facebook.com/tr` is included for visitors with JavaScript disabled.

This service is provided by Meta Platforms, Inc. Please review their terms and privacy policy, and make sure your site's own privacy policy and cookie consent notice disclose this tracking to your visitors:

* Meta Terms of Service: https://www.facebook.com/legal/terms/
* Meta Business Tools Terms: https://www.facebook.com/legal/terms/businesstools
* Meta Privacy Policy: https://www.facebook.com/privacy/policy/

== Changelog ==

= 1.1.0 =
* Initial release
* Sends server-side Purchase events to the Facebook Conversions API, plus browser Meta Pixel and Conversions API events fired together with a shared event_id for deduplication
* Server-side + browser ViewContent, AddToCart and InitiateCheckout events, with a REST endpoint so browser-initiated AddToCart events deduplicate against the server event
* Captures the _fbc and _fbp cookies at checkout (reconstructing fbc from an fbclid URL parameter when the cookie is unavailable) and includes them in the payload
* Hashes customer email, phone, name and address fields (SHA-256) before sending, per Facebook Advanced Matching
* Compatible with WooCommerce's High-Performance Order Storage (HPOS)
* Redirects to the settings screen on plugin activation
* Adds a Settings link to the plugin listing on the Plugins screen
* IMPORTANT: disable any other Meta/Facebook pixel (e.g. in Pixel Manager) to avoid duplicate browser events