PHPackages automattic/woocommerce-analytics - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. automattic/woocommerce-analytics ActiveJetpack-library[Utility & Helpers](/categories/utility) automattic/woocommerce-analytics ================================ Enhanced analytics for WooCommerce users. v0.16.1(1mo ago)417.2k↓15%11GPL-2.0-or-laterPHPPHP >=7.2CI passing Since Mar 12Pushed 1mo ago3 watchersCompare [ Source](https://github.com/Automattic/woocommerce-analytics)[ Packagist](https://packagist.org/packages/automattic/woocommerce-analytics)[ RSS](/packages/automattic-woocommerce-analytics/feed)WikiDiscussions trunk Synced 1mo ago READMEChangelogDependencies (18)Versions (60)Used By (1) WooCommerce Analytics ===================== [](#woocommerce-analytics) Overview -------- [](#overview) Enhanced analytics package for WooCommerce stores with comprehensive frontend tracking for Automattic based projects. ### Key Features [](#key-features) - **Comprehensive Event Tracking**: 25+ predefined events covering e-commerce, navigation, and user interactions - **Session Management**: Intelligent session tracking and user engagement metrics - **Proxy Tracking**: Optional proxy-based tracking for enhanced privacy and performance Installation & Setup ------------------------ [](#installation--setup) ### WordPress Plugin Integration [](#wordpress-plugin-integration) ``` // Add to your plugin use Automattic\Woocommerce_Analytics; add_action( 'after_setup_theme', function() { Woocommerce_Analytics::init(); } ); ``` #### Initialization [](#initialization) The package only starts tracking when: - WooCommerce 3.0 or higher is active and installed - Jetpack is connected - In site page context (not admin, ajax, xmlrpc, login, feed, cli, etc.) ### Requirements [](#requirements) - WordPress 5.0+ - WooCommerce 3.0+ - PHP 7.4+ ### Package Installation [](#package-installation) If you plan on using this package in your WordPress plugin, we recommend using [Jetpack Autoloader](https://packagist.org/packages/automattic/jetpack-autoloader) as your autoloader for maximum interoperability. Configuration ------------- [](#configuration) ### Feature Flags [](#feature-flags) Enable advanced features using WordPress filters: #### ClickHouse Tracking [](#clickhouse-tracking) ``` // Enable ClickHouse event tracking add_filter( 'woocommerce_analytics_clickhouse_enabled', '__return_true' ); ``` #### Proxy Tracking (Experimental) [](#proxy-tracking-experimental) ``` // Enable proxy tracking for enhanced privacy and performance add_filter( 'woocommerce_analytics_experimental_proxy_tracking_enabled', '__return_true' ); ``` Privacy & Consent Management -------------------------------- [](#privacy--consent-management) ### WP Consent API Integration [](#wp-consent-api-integration) The package integrates with [WP Consent API](https://wordpress.org/plugins/wp-consent-api/) to ensure GDPR and privacy regulation compliance. Tracking only occurs when users have granted consent for statistics collection. When WP Consent API is not available, the package defaults to allowing all tracking to maintain backward compatibility. Tracked Events -------------- [](#tracked-events) ### Session Events [](#session-events) Event NameTriggerClickHouseRecording MethodDescription`session_started`Page load✓JSWhen user session begins`session_engagement`Page load (returning session)✓JSWhen user visits site in existing session (engagement marker)### Navigation Events [](#navigation-events) Event NameTriggerClickHouseRecording MethodDescription`page_view`Page load✓JSGeneral page view tracking`search`Search action✓PHP → JS QueueWhen site search is performed### Store Events [](#store-events) Event NameTriggerClickHouseRecording MethodDescription`product_view`Single product page✓PHP → JS QueueWhen product page is viewed`cart_view`Cart page✓PHP → JS QueueWhen cart page is viewed`add_to_cart`Add to cart action✓PHP (Immediate)When products are added to cart`remove_from_cart`Remove from cart✓PHP (Immediate)When products are removed from cart`checkout_view`Checkout page✓PHP → JS QueueWhen checkout page is viewed`product_checkout`Checkout page✓PHP → JS QueueWhen checkout page is viewed and cart is not empty`product_purchase`Order placed✓PHP (Immediate)When purchase is completed`order_confirmation_view`Thank you page✓PHP → JS QueueWhen order confirmation page is viewed`post_account_creation`Account creation-PHP → JS QueueWhen new account is created during checkout### Account Events [](#account-events) Event NameTriggerClickHouseRecording MethodDescription`my_account_tab_click`Tab click-JSWhen account navigation log out tab is clicked`my_account_page_view`Tab view-PHP → JS QueueWhen account tabs/pages are viewed`my_account_order_number_click`Order number click-PHP → JS QueueWhen order number link is clicked`my_account_order_action_click`Order action click-PHP → JS QueueWhen order action buttons are clicked`my_account_address_click`Address link click-PHP → JS QueueWhen address edit links are clicked`my_account_address_save`Address update-PHP (Immediate)When user saves address information`my_account_payment_add`Payment method page-PHP → JS QueueWhen add payment method page is viewed`my_account_payment_save`Payment method add-PHP (Immediate)When payment method is added`my_account_payment_delete`Payment method delete-PHP (Immediate)When payment method is deleted`my_account_details_save`Profile update-PHP (Immediate)When account details are saved### Recording Methods Explained [](#recording-methods-explained) The **Recording Method** column shows how each event is processed: - **`JS`** - Pure client-side events recorded directly by JavaScript without server involvement - **`PHP → JS Queue`** - Server-side events that are queued during page generation and passed to frontend for transmission - **`PHP (Immediate)`** - Server-side events sent immediately when triggered via WordPress hooks/actions ### Event Properties [](#event-properties) Each event includes contextual data such as: - **Product Information**: ID, name, price, categories, SKU - **Cart Details**: Item quantities, totals, currency - **User Data**: Customer ID (when available and permitted) - **Session Information**: Session ID, engagement metrics - **Page Context**: URL, referrer, breadcrumbs - **Store Data**: Order ID, payment method, shipping info Architecture ------------ [](#architecture) ### PHP Backend [](#php-backend) - **`Woocommerce_Analytics`** - Main initialization class - **`Universal`** - Core tracking logic and WooCommerce hooks - **`My_Account`** - Account-specific event tracking - **`WC_Analytics_Tracking`** - Event queuing and processing - **`Features`** - Feature flag management ### Frontend [](#frontend) - **`Analytics`** - Main client-side analytics class - **`SessionManager`** - Session tracking and management - **`ApiClient`** - REST API communication for proxy tracking - **Event Listeners** - Page-specific event handlers ### Data Flow [](#data-flow) **PHP (Immediate)** events: 1. WooCommerce action/hook triggers PHP method 2. `WC_Analytics_Tracking::record_event()` called directly 3. Event sent immediately to Tracks and/or ClickHouse **PHP → JS Queue** events: 1. WooCommerce action/hook triggers PHP method 2. Event queued via `enqueue_event()` method 3. Queue injected into page via `window.wcAnalytics.eventQueue` 4. Frontend JavaScript processes queue and sends to `_wca` tracking pixel if proxy tracking is disabled, otherwise sent to Proxy API endpoint **JS** events: 1. Frontend JavaScript directly records events via `recordEvent()` 2. Events sent to `_wca` tracking pixel if proxy tracking is disabled, otherwise sent to Proxy API endpoint ### User Identification [](#user-identification) The package uses a hierarchical approach to identify users for analytics: **Anonymous User Identification (in order of preference):** 1. **`tk_ai` Cookie**: Primary method using Tracks anonymous identifier cookie 2. **IP-based ID** (when proxy tracking enabled): Generates visitor ID from: - Daily rotating salt (privacy-focused, changes daily) - Domain name - User IP address - User agent string - Creates SHA256 hash (16-char substring) for anonymous but consistent identification 3. If no `tk_ai` cookie and proxy tracking disabled: `null` (no visitor tracking) **Session Management:** - Session cookies (`woocommerceanalytics_session`) expire after 30 minutes or at midnight UTC (whichever comes first) - Used for tracking user journey within a session (separate from user identification) - Contains session ID, landing page, and engagement status Development ----------- [](#development) ``` # Build the client-side JavaScript pnpm run build # Development watch mode pnpm run watch ``` See [package.json](./package.json) for more commands. Advanced Topics --------------- [](#advanced-topics) ### Proxy Tracking [](#proxy-tracking) When proxy tracking is enabled: - Events are sent to a local WordPress REST API endpoint to improve event delivery reliability - Server-side event validation and processing #### API Endpoint [](#api-endpoint) - **URL**: `/wp-json/woocommerce-analytics/v1/track` - **Method**: POST - **Permission**: No authentication required - **Content-Type**: `application/json` #### Performance Optimizations [](#performance-optimizations) **Client-Side Batching Logic:** - Events queued until batch size (10 events) or debounce delay (1s) reached - Immediate flush on page unload (`beforeunload`, `pagehide` events) - Failed events automatically re-queued for retry **Server-Side Optimizations:** The package includes an optional MU plugin (`woocommerce-analytics-proxy-speed-module.php`) that significantly improves proxy performance by only loading WooCommerce, WooCommerce Analytics, and Jetpack for proxy requests ### Debugging [](#debugging) Enable debug mode for detailed logging: ``` // In browser console or add to page localStorage.setItem( 'debug', 'wc-analytics:*' ); ``` Security -------- [](#security) Need to report a security vulnerability? Go to or directly to our security bug bounty site . License ------- [](#license) woocommerce-analytics is licensed under [GNU General Public License v2 (or later)](./LICENSE.txt) ### Health Score 49 — FairBetter than 95% of packages Maintenance90 Actively maintained with recent releases Popularity32 Limited adoption so far Community30 Small or concentrated contributor base Maturity40 Maturing project, gaining track record Bus Factor3 3 contributors hold 50%+ of commits How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~13 days Recently: every ~7 days Total 58 Last Release 56d ago PHP version history (2 changes)v0.1.0PHP >=7.0 v0.2.0PHP >=7.2 ### Community Maintainers ![](https://www.gravatar.com/avatar/7c5869ecbb8e0eac7e8b8e0f3cf7bdd8d5fcdc4abc10a72281872c53f8639d44?d=identicon)[automattic](/maintainers/automattic) ![](https://www.gravatar.com/avatar/11609890f6e7a840715f4cfc9622d77ea64b7dfc024df5643fbf8471a18c00f3?d=identicon)[kraft](/maintainers/kraft) ![](https://www.gravatar.com/avatar/5326730499ec14e274f51b9bcc39db6aac0fb38b33849715aae0e2587a2b93df?d=identicon)[jeherve](/maintainers/jeherve) ![](https://www.gravatar.com/avatar/6e220e167e341c28b1aa10bf0bb0374999068329f8683d3187ee3cf6749b8837?d=identicon)[dereksmart](/maintainers/dereksmart) --- Top Contributors [![anomiex](https://avatars.githubusercontent.com/u/1030580?v=4)](https://github.com/anomiex "anomiex (101 commits)")[![tbradsha](https://avatars.githubusercontent.com/u/32492176?v=4)](https://github.com/tbradsha "tbradsha (93 commits)")[![chihsuan](https://avatars.githubusercontent.com/u/4344253?v=4)](https://github.com/chihsuan "chihsuan (38 commits)")[![jeherve](https://avatars.githubusercontent.com/u/426388?v=4)](https://github.com/jeherve "jeherve (25 commits)")[![gmjuhasz](https://avatars.githubusercontent.com/u/36671565?v=4)](https://github.com/gmjuhasz "gmjuhasz (23 commits)")[![manzoorwanijk](https://avatars.githubusercontent.com/u/18226415?v=4)](https://github.com/manzoorwanijk "manzoorwanijk (23 commits)")[![zinigor](https://avatars.githubusercontent.com/u/374293?v=4)](https://github.com/zinigor "zinigor (21 commits)")[![bindlegirl](https://avatars.githubusercontent.com/u/1242807?v=4)](https://github.com/bindlegirl "bindlegirl (21 commits)")[![sergeymitr](https://avatars.githubusercontent.com/u/1341249?v=4)](https://github.com/sergeymitr "sergeymitr (18 commits)")[![dilirity](https://avatars.githubusercontent.com/u/11799079?v=4)](https://github.com/dilirity "dilirity (10 commits)")[![kraftbj](https://avatars.githubusercontent.com/u/88897?v=4)](https://github.com/kraftbj "kraftbj (7 commits)")[![ice9js](https://avatars.githubusercontent.com/u/8056203?v=4)](https://github.com/ice9js "ice9js (7 commits)")[![LiamSarsfield](https://avatars.githubusercontent.com/u/43409125?v=4)](https://github.com/LiamSarsfield "LiamSarsfield (5 commits)")[![puntope](https://avatars.githubusercontent.com/u/5908855?v=4)](https://github.com/puntope "puntope (4 commits)")[![kangzj](https://avatars.githubusercontent.com/u/1425433?v=4)](https://github.com/kangzj "kangzj (3 commits)")[![zaerl](https://avatars.githubusercontent.com/u/167611?v=4)](https://github.com/zaerl "zaerl (3 commits)")[![haqadn](https://avatars.githubusercontent.com/u/3737780?v=4)](https://github.com/haqadn "haqadn (3 commits)")[![ArSn](https://avatars.githubusercontent.com/u/2803693?v=4)](https://github.com/ArSn "ArSn (3 commits)")[![darssen](https://avatars.githubusercontent.com/u/13239096?v=4)](https://github.com/darssen "darssen (3 commits)")[![oskosk](https://avatars.githubusercontent.com/u/746152?v=4)](https://github.com/oskosk "oskosk (2 commits)") ### Embed Badge ![Health badge](/badges/automattic-woocommerce-analytics/health.svg) ``` [![Health](https://phpackages.com/badges/automattic-woocommerce-analytics/health.svg)](https://phpackages.com/packages/automattic-woocommerce-analytics) ``` ### Alternatives [automattic/jetpack Jetpack supercharges your self‑hosted WordPress site with the awesome cloud power of WordPress.com 3621.9k](/packages/automattic-jetpack) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)