## 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:

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:

- 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:

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:

- 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 `WPDAI_WooCommerce_Event_Tracking->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:

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:

- 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:

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:

- 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:

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:

- 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:

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:

- 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:

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:

- 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