README

Overview

Enhanced analytics package for WooCommerce stores with comprehensive frontend tracking for Automattic based projects.

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

WordPress Plugin Integration

// Add to your plugin
use Automattic\Woocommerce_Analytics;

add_action(
 'after_setup_theme',
 function() {
  Woocommerce_Analytics::init();
 }
);

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

WordPress 5.0+
WooCommerce 3.0+
PHP 7.4+

Package Installation

If you plan on using this package in your WordPress plugin, we recommend using Jetpack Autoloader as your autoloader for maximum interoperability.

Configuration

Feature Flags

Enable advanced features using WordPress filters:

ClickHouse Tracking

// Enable ClickHouse event tracking
add_filter( 'woocommerce_analytics_clickhouse_enabled', '__return_true' );

Proxy Tracking (Experimental)

// Enable proxy tracking for enhanced privacy and performance
add_filter( 'woocommerce_analytics_experimental_proxy_tracking_enabled', '__return_true' );

Tracked Events

Session Events

Event Name	Trigger	ClickHouse	Recording Method	Description
`session_started`	Page load	✓	JS	When user session begins
`session_engagement`	Page load (returning session)	✓	JS	When user visits site in existing session (engagement marker)

Navigation Events

Event Name	Trigger	ClickHouse	Recording Method	Description
`page_view`	Page load	✓	JS	General page view tracking
`search`	Search action	✓	PHP → JS Queue	When site search is performed

Store Events

Event Name	Trigger	ClickHouse	Recording Method	Description
`product_view`	Single product page	✓	PHP → JS Queue	When product page is viewed
`cart_view`	Cart page	✓	PHP → JS Queue	When 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 Queue	When checkout page is viewed
`product_checkout`	Checkout page	✓	PHP → JS Queue	When 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 Queue	When order confirmation page is viewed
`post_account_creation`	Account creation	-	PHP → JS Queue	When new account is created during checkout

Account Events

Event Name	Trigger	ClickHouse	Recording Method	Description
`my_account_tab_click`	Tab click	-	JS	When account navigation log out tab is clicked
`my_account_page_view`	Tab view	-	PHP → JS Queue	When account tabs/pages are viewed
`my_account_order_number_click`	Order number click	-	PHP → JS Queue	When order number link is clicked
`my_account_order_action_click`	Order action click	-	PHP → JS Queue	When order action buttons are clicked
`my_account_address_click`	Address link click	-	PHP → JS Queue	When 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 Queue	When 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

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

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

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

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

PHP (Immediate) events:

WooCommerce action/hook triggers PHP method
WC_Analytics_Tracking::record_event() called directly
Event sent immediately to Tracks and/or ClickHouse

PHP → JS Queue events:

WooCommerce action/hook triggers PHP method
Event queued via enqueue_event() method
Queue injected into page via window.wcAnalytics.eventQueue
Frontend JavaScript processes queue and sends to _wca tracking pixel if proxy tracking is disabled, otherwise sent to Proxy API endpoint

JS events:

Frontend JavaScript directly records events via recordEvent()
Events sent to _wca tracking pixel if proxy tracking is disabled, otherwise sent to Proxy API endpoint

User Identification

The package uses a hierarchical approach to identify users for analytics:

Anonymous User Identification (in order of preference):

tk_ai Cookie: Primary method using Tracks anonymous identifier cookie
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
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

# Build the client-side JavaScript
pnpm run build

# Development watch mode
pnpm run watch

See package.json for more commands.

Advanced Topics

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

URL: /wp-json/woocommerce-analytics/v1/track
Method: POST
Permission: No authentication required
Content-Type: application/json

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

Enable debug mode for detailed logging:

// In browser console or add to page
localStorage.setItem('debug', 'wc-analytics:*');

Security

Need to report a security vulnerability? Go to https://automattic.com/security/ or directly to our security bug bounty site https://hackerone.com/automattic.

License

woocommerce-analytics is licensed under GNU General Public License v2 (or later)

automattic / woocommerce-analytics

Maintainers

Details