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:

Event Categories

Events are organized into these categories:

Page Events

page_view

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

When triggered:

Data captured:

Field Description Example
page_href Full URL of page viewed https://store.com/products/t-shirt
object_type WordPress post type page, post, product, category
object_id WordPress post/page ID 123
product_id Product ID (if product page) 123 (or 0 if not product)

Special handling:

Use in analysis:

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:

Data captured:

Field Description Example
product_id Product clicked 123
object_id Same as product_id 123
object_type Always "product" product
page_href Page where click occurred https://store.com/shop

Technical implementation:

Use in analysis:

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:

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:

Data captured:

Field Description Example
product_id Product purchased 123
variation_id Variation ID (if variable product) 456 (or 0)
event_quantity Quantity purchased 2
event_value Line item total (after discounts) 45.00
object_id Order ID 789
object_type Always "order" order

Use in analysis:

Cart Events

add_to_cart

Description: Tracks when a product is added to cart

When triggered:

Data captured:

Field Description Example
product_id Product added 123
variation_id Variation (if applicable) 456 (or 0)
event_quantity Quantity added 1
event_value Product price × quantity 29.99

Hook parameters captured:

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

Use in analysis:

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:

Data captured:

Use in analysis:

wc_cart_emptied

Description: Cart is emptied by user or system

When triggered:

Use in analysis:

Checkout Events

init_checkout

Description: User begins checkout process

When triggered:

Data captured:

Use in analysis:

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:

Data captured:

Field Description Example
page_href Checkout page URL https://store.com/checkout
additional_data JSON with error details {"error_message": "Invalid credit card"}

Error message capture:

Use in analysis:

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:

Use in analysis:

payment_method_selected

Description: User selects payment method

When triggered:

Use in analysis:

updated_shipping_method

Description: User changes shipping method

When triggered:

Use in analysis:

applied_coupon

Description: Coupon code applied to cart/checkout

When triggered:

Use in analysis:

removed_coupon

Description: Coupon removed from cart/checkout

When triggered:

Transaction Events

transaction

Description: Order successfully placed and paid

When triggered:

Data captured:

Field Description Example
event_value Order total (after discounts, before tax) 95.50
event_quantity Total items in order 3
object_id Order ID 789
object_type Always "order" order

Use in analysis:

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:

Data captured:

Use in analysis:

log_out

Description: User logs out

When triggered:

Use in analysis:

Form Events

form_submit

Description: Any form on the site is submitted

When triggered:

Data captured:

Field Description Example
additional_data Form metadata (JSON) See below

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:

Use in analysis:

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:

Example analyses:

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

Event Limitations

Troubleshooting Event Tracking

Events not appearing:

Some events missing:

Events show wrong data:

Next Steps