Event Types Reference

Alpha Insights tracks a comprehensive set of events to understand visitor behavior and eCommerce activity. This reference guide documents every event type tracked by the system, when they’re triggered, what data they capture, and how to use them in your analysis.

Event Overview

Events are individual actions taken by visitors on your website. Each event is stored with:

• Timestamp: When the event occurred (GMT)
• Session ID: Which session the event belongs to
• Event type: What action was taken
• Context: Page URL, object ID/type, product ID, etc.
• Value: Monetary value if applicable (for transactions)
• Additional data: Event-specific metadata (JSON)

Event Categories

Events are organized into these categories:

• Page Events: Page views and navigation
• Product Events: Product interactions
• Cart Events: Shopping cart activity
• Checkout Events: Checkout process
• Transaction Events: Completed purchases
• User Events: Authentication actions
• Form Events: Form submissions
• WooCommerce Events: WC-specific actions

Page Events

page_view

Description: Tracks when a visitor views any page on your website

When triggered:

• Automatically on every page load
• Fires on document.ready
• Tracked via JavaScript

Data captured:

Special handling:

• If page is checkout page (ID matches wc_get_page_id('checkout')), also triggers init_checkout event
• If page is cart page (ID matches wc_get_page_id('cart')), also triggers viewed_cart_page event
• Product pages automatically set product_id field

Use in analysis:

• Calculate total page views
• Determine pages per session
• Identify most popular pages
• Analyze navigation patterns
• Calculate bounce rate (1 page view = bounce)

Example query:

SELECT page_href, COUNT(*) as views
FROM wp_wpd_ai_events
WHERE event_type = 'page_view'
AND date_created_gmt >= '2024-01-01'
GROUP BY page_href
ORDER BY views DESC
LIMIT 10;

Product Events

product_click

Description: Tracks when a visitor clicks on a product link in category/shop pages

When triggered:

• User clicks any <a> tag inside .products .product container
• Typically on shop, category, or archive pages
• Tracked via JavaScript click event

Data captured:

Technical implementation:

• Product ID captured from hidden element with class .wpd-ai-event-tracking-product-id and data attribute data-product-id
• This element added automatically by WPD_WooCommerce_Events->add_product_id_to_product_loop_item()

Use in analysis:

• Identify most clicked products
• Calculate click-through rate from category to product page
• Measure product interest vs actual views
• Compare clicks to purchases (conversion funnel)

product_page_view

Description: A page_view event where object_type = 'product'

When triggered: When visitor views a product page

Data captured: Same as page_view but with product-specific fields populated

Use in analysis:

• Count product page views
• Identify most viewed products
• Calculate view-to-purchase rate
• Compare product interest across categories

Example query:

SELECT product_id, COUNT(*) as views
FROM wp_wpd_ai_events
WHERE event_type = 'page_view'
AND object_type = 'product'
AND date_created_gmt >= DATE_SUB(NOW(), INTERVAL 30 DAY)
GROUP BY product_id
ORDER BY views DESC
LIMIT 20;

product_purchase

Description: Individual product purchase within an order

When triggered:

• Order status changes to a paid status (processing, completed)
• Tracked server-side via woocommerce_order_status_changed hook
• One event per line item in order

Data captured:

Use in analysis:

• Identify bestselling products
• Calculate product revenue
• Analyze product purchase frequency
• Compare product performance

Cart Events

add_to_cart

Description: Tracks when a product is added to cart

When triggered:

• Server-side via woocommerce_add_to_cart hook
• Fires after product successfully added to cart
• Most reliable cart tracking (server-side)

Data captured:

Hook parameters captured:

woocommerce_add_to_cart($cart_item_key, $product_id, $quantity, $variation_id, $variation, $cart_item_data)

Use in analysis:

• Calculate add-to-cart rate (adds / product views)
• Identify most added products
• Track cart abandonment (adds without transactions)
• Measure product interest

Funnel analysis:

Product Views → Add to Cart → Init Checkout → Transaction
     1000            250             100              75
                   25% rate         40% rate       75% rate

viewed_cart_page

Description: Visitor views the cart page

When triggered:

• Automatically when cart page is viewed
• Derived from page_view event on cart page
• Processed server-side in REST API handler

Data captured:

• Standard page view data
• Page URL is cart page
• Object ID matches wc_get_page_id('cart')

Use in analysis:

• Count cart page views
• Calculate cart abandonment rate
• Measure checkout funnel dropoff
• Identify sessions with cart views but no purchase

wc_cart_emptied

Description: Cart is emptied by user or system

When triggered:

• User clicks “clear cart” or similar action
• Triggered by WooCommerce JavaScript event
• Tracked via JavaScript listener

Use in analysis:

• Measure cart abandonment patterns
• Identify frustration points
• Analyze pre-purchase behavior

Checkout Events

init_checkout

Description: User begins checkout process

When triggered:

• Automatically when checkout page is viewed
• Derived from page_view event on checkout page
• Processed server-side in REST API handler

Data captured:

• Standard page view data
• Page URL is checkout page
• Object ID matches wc_get_page_id('checkout')

Use in analysis:

• Count checkout initiations
• Calculate checkout abandonment rate
• Measure conversion funnel
• Identify checkout dropoff

Funnel example:

Cart Views: 150
Init Checkout: 100 (66.7% continue to checkout)
Transactions: 75 (75% complete purchase)

viewed_checkout_page

Description: Same as init_checkout (tracked as separate event type for clarity)

checkout_error

Description: Error occurs during checkout process

When triggered:

• WooCommerce fires checkout_error JavaScript event
• Form validation fails
• Payment gateway error
• Tracked via JavaScript with 300ms delay (to capture error messages)

Data captured:

Error message capture:

• Reads text from .woocommerce-error and .woocommerce-notices-wrapper elements
• Stored in additional_data->error_message
• 300ms delay allows AJAX-loaded errors to appear

Use in analysis:

• Identify common checkout errors
• Measure checkout friction
• Calculate error rate (errors / checkout initiations)
• Prioritize checkout improvements
• Track payment gateway issues

Example analysis:

SELECT JSON_EXTRACT(additional_data, '$.error_message') as error,
       COUNT(*) as occurrences
FROM wp_wpd_ai_events
WHERE event_type = 'checkout_error'
AND date_created_gmt >= DATE_SUB(NOW(), INTERVAL 7 DAY)
GROUP BY error
ORDER BY occurrences DESC;

updated_checkout

Description: Checkout form is updated/recalculated

When triggered:

• Shipping method changed
• Billing/shipping address changed
• Coupon applied
• WooCommerce fires updated_checkout event

Use in analysis:

• Measure checkout engagement
• Count form interactions
• Identify checkout complexity

payment_method_selected

Description: User selects payment method

When triggered:

• User clicks different payment option
• WooCommerce fires payment_method_selected event

Use in analysis:

• Track payment method preferences
• Identify payment gateway issues
• Measure checkout progression

updated_shipping_method

Description: User changes shipping method

When triggered:

• User selects different shipping option
• WooCommerce fires updated_shipping_method event

Use in analysis:

• Track shipping preferences
• Measure shipping cost sensitivity
• Identify free shipping impact

applied_coupon

Description: Coupon code applied to cart/checkout

When triggered:

• User successfully applies coupon
• WooCommerce fires applied_coupon event

Use in analysis:

• Track coupon usage
• Measure promotion effectiveness
• Identify discount-driven purchases

removed_coupon

Description: Coupon removed from cart/checkout

When triggered:

• User removes coupon
• WooCommerce fires removed_coupon event

Transaction Events

transaction

Description: Order successfully placed and paid

When triggered:

• Order status changes to paid status (processing, completed)
• Tracked server-side via woocommerce_order_status_changed hook
• One event per order
• Most important conversion event

Data captured:

Use in analysis:

• Calculate total revenue
• Count transactions
• Calculate conversion rate (transactions / sessions)
• Measure average order value
• Link orders to traffic sources
• Calculate profit per session

Key metrics:

Conversion Rate = (Transactions / Sessions) × 100
Revenue Per Session = Total Revenue / Total Sessions
Average Order Value = Total Revenue / Total Transactions

User Events

log_in

Description: User successfully logs in

When triggered:

• Server-side via wp_login hook
• Also via woocommerce_customer_login hook
• Fires after successful authentication

Data captured:

• User ID populated
• Login page URL
• Timestamp

Use in analysis:

• Track returning customers
• Measure account usage
• Analyze logged-in vs guest checkout

log_out

Description: User logs out

When triggered:

• Server-side via wp_logout hook
• Fires before user session ends

Use in analysis:

• Track session end behavior
• Measure account engagement

Form Events

form_submit

Description: Any form on the site is submitted

When triggered:

• JavaScript listener on all <form> submit events
• Fires before form actually submits
• Tracked via jQuery $('body').on('submit', 'form')

Data captured:

additional_data structure:

{
  "form_id": ".search-form",  // or ID/name if available
  "form_element_id": "searchform",
  "form_element_name": "s",
  "form_element_class": "search-form header-search",
  "form_element_action": "/search",
  "form_method": "get"
}

Security:

• Password fields explicitly filtered out
• Form data itself NOT stored (only metadata)
• Privacy-safe tracking

Use in analysis:

• Track search usage
• Measure contact form submissions
• Identify most-used forms
• Calculate form conversion rates

Event Data Structure

Standard fields for all events:

{
  // Identity
  "session_id": "wpd5f4dcc3b5aa76...",
  "ip_address": "192.168.1.1",
  "user_id": 0,  // 0 = guest, >0 = logged in user
  
  // Context
  "page_href": "https://yourstore.com/products/t-shirt",
  "object_type": "product",  // post type or 'order'
  "object_id": 123,          // post/page/product/order ID
  
  // Event details
  "event_type": "page_view",
  "event_quantity": 1,
  "event_value": 0.00,       // monetary value
  
  // Product context (if applicable)
  "product_id": 123,         // 0 if not product-related
  "variation_id": 0,         // 0 if not variation
  
  // Metadata
  "date_created_gmt": "2024-03-15 14:30:25",
  "additional_data": "{}"    // JSON string
}

Event Filtering & Analysis

Events can be filtered in reports using the Report Builder. See Using Report Filters for complete filtering options.

Common Queries

1. Count events by type:

SELECT event_type, COUNT(*) as count
FROM wp_wpd_ai_events
WHERE date_created_gmt >= DATE_SUB(NOW(), INTERVAL 7 DAY)
GROUP BY event_type
ORDER BY count DESC;

2. Page view count:

SELECT COUNT(*) as page_views
FROM wp_wpd_ai_events
WHERE event_type = 'page_view'
AND date_created_gmt >= '2024-01-01';

3. Conversion funnel:

SELECT 
  SUM(CASE WHEN event_type = 'product_page_view' THEN 1 ELSE 0 END) as product_views,
  SUM(CASE WHEN event_type = 'add_to_cart' THEN 1 ELSE 0 END) as add_to_carts,
  SUM(CASE WHEN event_type = 'init_checkout' THEN 1 ELSE 0 END) as checkouts,
  SUM(CASE WHEN event_type = 'transaction' THEN 1 ELSE 0 END) as transactions
FROM wp_wpd_ai_events
WHERE date_created_gmt >= DATE_SUB(NOW(), INTERVAL 30 DAY);

4. Events per session:

SELECT session_id, 
       COUNT(*) as events,
       SUM(CASE WHEN event_type = 'page_view' THEN 1 ELSE 0 END) as page_views
FROM wp_wpd_ai_events
WHERE date_created_gmt >= DATE_SUB(NOW(), INTERVAL 1 DAY)
GROUP BY session_id
ORDER BY events DESC
LIMIT 10;

Using Events in Reports

In Report Builder:

• Filter by event type: session_contains_event filter
• Analyze sessions with specific events
• Compare sessions with/without events

Example analyses:

• Sessions with checkout errors vs those without
• Sessions with form submissions
• Sessions with product clicks but no purchases
• Sessions with multiple page views (engaged visitors)

Custom Event Tracking

You can track custom events beyond the standard eCommerce events. For advanced custom implementations, see the Developer Documentation.

JavaScript Custom Events

// Track custom button click
var payload = {
  event_type: 'custom_button_click',
  event_value: 0,
  additional_data: {
    button_text: 'Learn More',
    button_location: 'homepage_hero'
  }
};
WpdAiEventTracking(payload);

PHP Custom Events

// Track custom action server-side
$event_data = array(
  'event_type'     => 'video_watched',
  'event_quantity' => 1,
  'event_value'    => 0,
  'object_id'      => get_the_ID(),
  'object_type'    => 'page',
  'additional_data' => array(
    'video_id' => 'intro-video',
    'duration_seconds' => 120
  )
);
wpd_send_woocommerce_event($event_data);

Event Tracking Best Practices

• Don’t over-track: Too many events can clutter data and slow site
• Use meaningful event names: Descriptive, consistent naming
• Include context in additional_data: Store relevant metadata
• Test custom events: Verify they appear in Realtime Dashboard
• Document custom events: Maintain list of custom event types
• Clean up unused events: Periodically review and remove
• Consider performance: Each event = database write

Event Limitations

• Rate limiting: Max 60 events per minute per IP
• No retroactive tracking: Only tracks from enablement forward
• Cookie dependency: Requires cookies enabled
• JavaScript dependency: Most events require JS enabled
• Session-based: Events tied to sessions (10-minute timeout)
• Single-domain: Doesn’t track cross-domain behavior

Troubleshooting Event Tracking

Events not appearing:

• Check if analytics is enabled (Settings → General Settings)
• Verify you’re not in excluded user role
• Check browser console for JavaScript errors
• Test REST API endpoint manually
• Check rate limiting (transient: wpd_ai_rate_limit_{ip})

Some events missing:

• Check if bot (user agent filtered)
• Verify cookies are enabled
• Check if landing page cookie is set
• Review server logs for errors

Events show wrong data:

• Check if custom theme overrides WC templates
• Verify product ID elements exist on category pages
• Check if AJAX is interfering with tracking
• Review JavaScript console for errors

Next Steps

• Review Technical Architecture for implementation details
• Read Session Management to understand event grouping
• Check Troubleshooting Guide for common issues
• See Report Filters to filter by event types
• Learn about Data Table Widget to display event data
• Explore Developer Documentation for custom events