Changeset 3426147

Timestamp:

12/23/2025 11:29:44 AM (2 months ago)

Author:

kayavanvliet

Message:

Improve readme.txt (features + messaging

File:

• tracksharp/trunk/readme.txt (modified) (2 diffs)

tracksharp/trunk/readme.txt

@@ -1 @@
-=== TrackSharp – Server Side Tracking for WooCommerce ===
+=== TrackSharp - Server-Side Tracking for WooCommerce ===
 Contributors: kayavanvliet
-Donate link:
-Tags: woocommerce, google analytics, ga4, server side tracking, conversion tracking
+Tags: woocommerce, ga4, google analytics, measurement protocol, server-side tracking, conversion tracking
 Requires at least: 6.1
 Tested up to: 6.9
@@ -10 +9 @@
 License URI: https://www.gnu.org/licenses/gpl-2.0.html
 
-Server-side conversion tracking for WooCommerce. Send GA4 purchase events via Measurement Protocol to rescue conversions lost to ad blockers and ITP.
+Stop losing WooCommerce revenue in GA4. TrackSharp sends purchase events server-side and gives you a dashboard + event log to verify tracking.
 
 == Description ==
 
-**TrackSharp** is a first-party server-side tracking plugin for WooCommerce that sends purchase events directly from your server to Google Analytics 4.
+TrackSharp is built for store owners who run ads and want reliable conversion tracking.
 
-🎯 **Rescue lost conversions** – Ad blockers, ITP, and browser restrictions block up to 30% of client-side tracking. TrackSharp sends events server-to-server, ensuring your conversions are counted.
+Browser tracking can be blocked or fail to fire (ad blockers, ITP, fast checkouts, users closing the tab). TrackSharp adds a first-party, server-side layer so your most important event (Purchase) is still recorded in Google Analytics 4.
 
-### Free Features
+= What you get (Free) =
 
-✅ **GA4 Server-Side Tracking** – Send purchase events via Measurement Protocol
-✅ **WooCommerce Integration** – Automatic order tracking with session stitching
-✅ **Consent-Aware** – Honors WP Consent API categories (`statistics`, `statistics-anonymous`)
-✅ **Dashboard & Event Log** – See tracked orders, revenue, and event status
-✅ **Setup Wizard** – Simple step-by-step configuration
-✅ **First-Party REST API** – Collect browser events via your own domain
+* GA4 server-side Purchase tracking (Measurement Protocol)
+* WooCommerce order stitching (first-party session ID + GA client ID capture during checkout)
+* Dashboard + Events Log (audit table + CSV export) so you can prove what was sent
+* Setup Wizard (Measurement ID + API secret + consent settings)
+* Consent-aware sending via the WP Consent API (`statistics` / `statistics-anonymous`)
+* Optional first-party collector endpoint (`/wp-json/tracksharp/v1/p`) used for logging and advanced setups
 
-### Pro Features 🔒
+Note: Besides Purchase, TrackSharp can also send key ecommerce events to GA4 via the first-party collector (for example: `view_item`, `add_to_cart`, `begin_checkout`, `add_shipping_info`, `add_payment_info`). Purchase is always sent from the WooCommerce order flow.
 
-Upgrade to TrackSharp Pro for advanced tracking capabilities:
+= Upgrade to Pro (optional) =
 
-🚀 **Meta Conversions API** – Server-side tracking for Facebook/Instagram ads with full user_data hashing
-🚀 **Google Ads Attribution** – Capture and pass gclid, gbraid, wbraid for proper conversion attribution
-🚀 **Enhanced Conversions** – SHA-256 hashed user data (email, phone, address) for improved GA4 matching
-🚀 **Priority Support** – Get help directly from the developers
+If you want full ads-platform attribution (not just GA4), TrackSharp Pro adds:
 
-[View Pro Plans →](https://tracksharp.com)
+* Meta Conversions API (CAPI) with user data hashing
+* Google Ads click ID capture and attribution fields (gclid / gbraid / wbraid)
+* Enhanced Conversions (hashed user data for better matching)
+* Priority support
 
-### How It Works
+Pro plans: https://tracksharp.nl
 
-1. A customer places an order in WooCommerce
-2. TrackSharp captures session data and ad click identifiers
-3. After payment, the purchase event is sent **server-to-server** to GA4
-4. Your conversion is counted even if the browser blocked client-side tracking
+== How It Works ==
 
-### Consent & Privacy
+1. Customer checks out in WooCommerce.
+2. TrackSharp captures a first-party session ID and GA identifiers during checkout.
+3. When the order is paid, TrackSharp sends a server-side Purchase to GA4.
+4. Use TrackSharp -> Dashboard and TrackSharp -> Events to verify and troubleshoot.
 
-- Integrates with **WP Consent API** and popular CMPs
-- GA4 events require `statistics` consent (configurable)
-- Fallback behavior when no CMP is installed (configurable in settings)
+== Consent & Privacy ==
 
-### What Gets Stored
+* If the WP Consent API is present, TrackSharp only sends GA4 events when the configured consent category is granted (default: `statistics` or `statistics-anonymous`).
+* If no WP Consent API / CMP is present, TrackSharp uses a configurable fallback behavior (default: grant immediately).
 
-- Custom table: `{prefix}_ws_events` (event audit log)
-- Order meta: session ID, GA4 client ID, consent state
-- Cookie: `ws_session_id` (first-party session tracking)
+== What Data Is Stored ==
 
-### Admin Pages
-
-- **Dashboard** – Overview of tracked orders and revenue
-- **Events Log** – Raw event log with filters and CSV export
-- **Settings** – GA4 credentials and consent configuration
-- **Setup Wizard** – Step-by-step setup with test functionality  
-
-### Consent specifics
-
-- If WP Consent API is active, TrackSharp checks:
-  - **Meta**: `marketing` must be granted.
-  - **GA4**: `statistics` or `statistics-anonymous` (filterable).
-- If no WP Consent API is found, a **fallback** applies (default: “Grant immediately”). You can change this in **TrackSharp → Settings**.
-
-### Filters & actions (developer hooks)
-
-
-**Filters:**
-- `tracksharp_ga4_requires_marketing` (bool): require `marketing` for GA4 (default `false`).
-- `tracksharp_tracker_is_consent_granted` (bool, array $payload): override final consent decision per request.
-- `tracksharp_tracker_frontend_consent` (array): seed consent for the front-end script.
-- `tracksharp_session_cookie_category` (string): category required to set the session cookie (default `functional`).
-- `tracksharp_consent_category_marketing` / `tracksharp_consent_category_statistics` / `tracksharp_consent_category_statistics_anonymous` (strings): remap category slugs.
-- `tracksharp_blocked_log_events` (array): event names to **exclude** from audit log (default `view_item`, `viewcontent`, `pageview`).
-- `tracksharp_ga4_host` (string): override GA4 MP endpoint host.
-
-**Actions:**
-- `tracksharp_prune_events` (daily cron)  
+* Custom table: `{$wpdb->prefix}ws_events` (event audit log)
+* Order meta: session ID, GA client ID, consent snapshot
+* Cookie: `ws_session_id` (first-party session ID)
 
 == Installation ==
 
-1. Upload the plugin folder to `/wp-content/plugins/` or install via the Plugins screen.
-2. Activate the plugin.
-3. Go to **TrackSharp → Setup Wizard** and:
-   - Enter your **GA4 Measurement ID** and **API Secret**
-   - (Pro) Configure Meta Conversions API credentials
-4. (Recommended) Install **WP Consent API** and a CMP for consent management.
-5. Make a test order and check **TrackSharp → Events** to verify tracking.
+1. Install and activate the plugin.
+2. Go to TrackSharp -> Setup Wizard.
+3. Enter your GA4 Measurement ID and Measurement Protocol API Secret.
+4. (Recommended) Use a CMP that integrates with the WP Consent API.
+5. Place a test order and review TrackSharp -> Events.
 
 == Frequently Asked Questions ==
 
-= Does this replace my GA4/Meta browser tags? =
-No. TrackSharp complements your browser tags with reliable **server-to-server** events. You can keep your browser tags for attribution, deduping, and non-purchase events.
+= Does this replace my GA4 browser tags? =
+No. TrackSharp adds server-side tracking for purchases (and optionally other ecommerce events).
 
-= How are events deduplicated? =
-The plugin uses deterministic `event_id` values (e.g., `purchase_{$order_id}`) and sends a **browser breadcrumb** (audit-only) while the **server event** is the authoritative hit for GA4/Meta. On GA4, Measurement Protocol also carries session parameters for proper attribution.
+If you are already sending a browser `purchase` event (for example via GTM), make sure you avoid double counting in GA4:
+* disable the browser purchase tag, or
+* configure deduplication by using the same `event_id` for browser and server purchases.
+
+= How does GA4 deduplication work? =
+GA4 can deduplicate browser and Measurement Protocol events when the events share the same `event_name` and `event_id` (and are associated with the same user/session). TrackSharp uses deterministic `event_id` values for its server-side Purchase events (based on the WooCommerce order ID).
+
+= Does this work without WooCommerce? =
+No. TrackSharp is built for WooCommerce orders and will only send Purchase events when WooCommerce is active.
 
 = Is it GDPR compliant? =
-TrackSharp integrates with **WP Consent API**. GA4 is allowed under `statistics` or `statistics-anonymous` (configurable), Meta under `marketing`. With no CMP, you can choose a fallback policy (default: grant immediately).
-
-= What cookies does it set? =
-- `ws_session_id` — first-party session ID (functional/statistics-gated).
-- `ws_atc` — short-lived Add-to-Cart replay cookie (marketing-gated).
-The plugin also reads first-party copies of ad cookies (`_fbp`, `_fbc`) if present.
-
-= Which data is stored in the database? =
-An audit log in `{$wpdb->prefix}ws_events` with timestamp, channel, source, event name, HTTP status, consent, user-agent, and (if present) transaction ID and event ID.
-
-= Does it support non-WooCommerce events? =
-The built-in JS can post custom events to the first-party collector, but the S2S purchase stitching is tailored for WooCommerce.
+TrackSharp integrates with the WP Consent API and can be configured to respect your consent categories. You are responsible for your legal basis and privacy policy disclosures.
 
 == Screenshots ==
 
-1. Dashboard – rescued conversions overview
-2. Events log with filters (channel/source/OK/HTTP)
-3. Settings – GA4 / Meta credentials
-4. Setup Wizard
+1. Dashboard - overview of server-tracked orders and audit metrics
+2. Events Log - filters (channel/source/status) and CSV export
+3. Settings - GA4 credentials and consent settings (with optional Pro upgrade links)
+4. Setup Wizard - guided setup and test tools
 
 == Changelog ==
 
-= 1.0.0 =
-* Initial release (TrackSharp UI/branding).
-* GA4 Measurement Protocol with Enhanced Conversions.
-* Meta Conversions API with hashed user_data and fbp/fbc.
-* WP Consent API integration with stats/marketing categories (+ statistics-anonymous for GA4).
-* WooCommerce order stitching and S2S purchase sending.
-* Events Log table + CSV export.
-* Setup Wizard and Test Console.
-* First-party REST collector (`/wp-json/tracksharp/v1/p`).
+= 1.2.2 =
+* Initial WordPress.org release.
+* GA4 server-side Purchase tracking (Measurement Protocol).
+* Dashboard + Events Log (audit table + CSV export).
+* WP Consent API integration + setup wizard.
 
 == Upgrade Notice ==
 
-= 1.0.0 =
-Brand-new release.
-
-== Privacy ==
-
-TrackSharp processes event data for analytics and advertising measurement. User-provided data sent to Meta/GA4 is hashed (SHA-256) server-side when raw values are provided. Enable a CMP with WP Consent API to ensure events are sent only when the correct categories are granted. Review your legal basis and privacy policy accordingly.
+= 1.2.2 =
+Initial release on WordPress.org.
 
 == Third Party Services ==
 
-This plugin connects to the following external services:
+This plugin can connect to the following external services:
 
-**Google Analytics 4 (Measurement Protocol)**
-TrackSharp sends purchase and conversion events server-side to Google Analytics 4 using the Measurement Protocol API. This occurs when GA4 is configured with a Measurement ID and API Secret in the plugin settings.
-- Service: https://www.google-analytics.com
-- Terms: https://policies.google.com/terms
-- Privacy Policy: https://policies.google.com/privacy
+= Google Analytics 4 (Measurement Protocol) =
+TrackSharp sends server-side events to Google Analytics 4 when you configure a Measurement ID and Measurement Protocol API Secret.
+* Service: https://www.google-analytics.com
+* Terms: https://policies.google.com/terms
+* Privacy Policy: https://policies.google.com/privacy
 
-**Meta (Facebook) Conversions API**
-TrackSharp sends purchase events server-side to Meta (Facebook) using the Conversions API. This occurs when Meta is configured with a Pixel ID and Access Token in the plugin settings. User data is hashed (SHA-256) before transmission as required by Meta.
-- Service: https://graph.facebook.com
-- Terms: https://www.facebook.com/terms.php
-- Privacy Policy: https://www.facebook.com/privacy/policy
+= Meta (Facebook) Conversions API (Pro only) =
+When using TrackSharp Pro, purchase events can be sent server-side to Meta (Facebook) using the Conversions API.
+* Service: https://graph.facebook.com
+* Terms: https://www.facebook.com/terms.php
+* Privacy Policy: https://www.facebook.com/privacy/policy
 
-**Freemius (Licensing & Updates)**
-This plugin uses Freemius for plugin updates and to display optional upgrade options. If you choose to upgrade to Pro, Freemius handles license management for the Pro version and exchanges data with Freemius servers.
-- Service: https://freemius.com
-- Terms: https://freemius.com/terms/
-- Privacy Policy: https://freemius.com/privacy/
-
+= Freemius (upgrades, Pro licensing, and updates) =
+TrackSharp uses Freemius to display optional upgrade options and to manage licensing/updates for the Pro version.
+* Service: https://freemius.com
+* Terms: https://freemius.com/terms/
+* Privacy Policy: https://freemius.com/privacy/