Tracking Custom Events

Alpha Insights lets you record custom events from the frontend (JavaScript) or the backend (PHP). Custom events appear in your analytics alongside built-in events (page views, add to cart, purchase, etc.) so you can measure conversions, engagement, and business-specific actions.

Overview

You can track custom events in two ways:

• JavaScript (frontend): Fire events from the browser when the user does something (e.g. click a CTA, play a video, submit a form). Uses the same REST API as the built-in event tracking script.
• PHP (backend): Fire events from server-side code (hooks, shortcodes, templates) when something happens (e.g. form processed, lead captured, custom conversion). Uses a simple wrapper function that fills in session data automatically.

Both methods write to the same events table (wp_wpd_ai_woocommerce_events) and respect the same settings (event tracking enabled, user exclusions, rate limiting). For a list of built-in event types, see Event Types Reference.

Tracking Custom Events from JavaScript (Frontend)

The event tracking script exposes a global function WpdAiEventTracking() that sends a single event to the Alpha Insights API. Use it anywhere in your theme or plugin JavaScript after the tracking script has loaded.

Basic usage

WpdAiEventTracking({
    event_type: 'your_custom_event_name',
    event_quantity: 1,           // Optional, default 1
    event_value: 0,              // Optional, default 0
    object_id: 123,              // Optional, default current post ID
    object_type: 'product',      // Optional, default current post type
    product_id: 456,             // Optional, default 0
    variation_id: 789,           // Optional, default 0
    additional_data: {           // Optional, default {}
        custom_field: 'value',
        another_field: 'another_value'
    }
});

Required: Only event_type is required. All other fields are optional and default to the current context (page, post type, etc.) when omitted.

Parameter reference (JavaScript)

Example: Track a CTA click

jQuery('.my-cta-button').on('click', function() {
    WpdAiEventTracking({
        event_type: 'cta_click',
        additional_data: {
            cta_id: jQuery(this).data('cta-id'),
            cta_location: 'hero'
        }
    });
});

Example: Track a form submission (non-cart)

jQuery('#my-lead-form').on('submit', function() {
    WpdAiEventTracking({
        event_type: 'lead_form_submit',
        object_id: 0,
        object_type: 'form',
        additional_data: {
            form_id: 'my-lead-form',
            form_name: 'Contact'
        }
    });
});

Example: Track a video play

document.querySelector('#promo-video').addEventListener('play', function() {
    if (typeof WpdAiEventTracking === 'function') {
        WpdAiEventTracking({
            event_type: 'video_play',
            additional_data: {
                video_id: this.getAttribute('data-video-id'),
                video_title: 'Product Demo'
            }
        });
    }
});

Notes (JavaScript)

• Events are only sent if event tracking is enabled in Alpha Insights → Settings.
• The tracking script must be loaded on the page (it is enqueued automatically when event tracking is enabled).
• Events are sent asynchronously (sendBeacon or AJAX). There is no need to wait for a response unless you are handling success/error.
• If engaged-session tracking is enabled, the first page view may wait for user interaction; custom events still send immediately when you call WpdAiEventTracking().

Tracking Custom Events from PHP (Backend)

Use the single function wpdai_track_custom_event( $event_type, $args ) to record custom events from server-side code (hooks, shortcodes, templates, form handlers). Core params—session_id, ip_address, user_id, and page_href—are set automatically from the current session when you don’t pass them. Pass them in $args only when you need to override (e.g. server-side or headless context where you have your own session/request context).

wpdai_track_custom_event()

wpdai_track_custom_event( string $event_type, array $args = array() );

Parameters:

• $event_type (string, required) — The event type name (e.g. newsletter_signup, download_lead_magnet, custom_conversion).
• $args (array, optional) — Event data. Any key you omit is filled from the current session or defaults. Supported keys are listed below.

Returns: An array with success (bool), message (string), code (string), and rows_inserted (int). Use this to log or handle failures.

$args keys (PHP)

Core params (set automatically from session when not provided; override only if needed):

Event params:

Example: Track after form processing (hook)

add_action( 'my_plugin_lead_submitted', 'wpd_my_track_lead_event', 10, 2 );

function wpd_my_track_lead_event( $lead_id, $form_data ) {
    wpdai_track_custom_event( 'lead_submitted', array(
        'object_id'       => 0,
        'object_type'     => 'lead_form',
        'additional_data' => array(
            'lead_id'   => $lead_id,
            'form_name' => isset( $form_data['form_name'] ) ? $form_data['form_name'] : '',
        ),
    ) );
}

Example: Track a custom conversion with value

// After a quote request is saved
wpdai_track_custom_event( 'quote_request', array(
    'event_value'      => 0,
    'object_id'        => get_the_ID(),
    'object_type'      => get_post_type(),
    'additional_data'  => array(
        'quote_id' => $quote_id,
        'source'   => 'contact_page',
    ),
) );

Example: Track from a shortcode (e.g. download link page view)

add_shortcode( 'wpd_track_download', 'wpd_shortcode_track_download' );

function wpd_shortcode_track_download( $atts ) {
    $atts = shortcode_atts( array(
        'resource_id' => '',
        'label'       => 'Download',
    ), $atts, 'wpd_track_download' );

    $url = get_permalink( $atts['resource_id'] );
    if ( ! $url ) {
        return '';
    }

    // Track that the user saw this download CTA (fires when shortcode is rendered)
    wpdai_track_custom_event( 'resource_download_view', array(
        'object_id'       => (int) $atts['resource_id'],
        'object_type'     => 'resource',
        'additional_data' => array(
            'label' => sanitize_text_field( $atts['label'] ),
        ),
    ) );

    return '<a href="' . esc_url( $url ) . '" class="wpd-download-link">' . esc_html( $atts['label'] ) . '</a>';
}

To track the actual click or file download, use JavaScript WpdAiEventTracking() on the link click, or call wpdai_track_custom_event() from a redirect handler that runs when the user hits your download endpoint.

Example: Overriding core params (e.g. server-side context)

// When you have your own session/request context (e.g. webhook or background job)
wpdai_track_custom_event( 'server_side_conversion', array(
    'session_id'      => $stored_session_id,
    'ip_address'      => $customer_ip,
    'user_id'         => $customer_user_id,
    'page_href'       => home_url( '/thank-you/' ),
    'event_value'     => 99.00,
    'object_id'       => 456,
    'object_type'     => 'product',
    'product_id'      => 456,
    'additional_data' => array( 'campaign' => 'summer_sale' ),
) );

If you omit session_id, ip_address, user_id, or page_href, they are set automatically from the current Alpha Insights session and request.

Notes (PHP)

• Events are not inserted in the admin area, during CRON, or when event tracking is disabled. The same user/role exclusions and rate limits as frontend tracking apply.
• Insertion can fail if there is no valid session/landing page (e.g. server-side-only or headless request). Check the returned success and code if you need to handle failures.
• Custom event types appear in reports and filters like built-in events; use a consistent naming convention (e.g. snake_case) for easier analysis.

Viewing Custom Events in Reports

Custom events are stored in the same table as built-in events. In Alpha Insights reports you can:

• Filter or group by event_type to see your custom event names.
• Use Website Traffic and event-based metrics to count custom events, events per session, and conversion rates.
• Use additional_data in exports or custom queries for deeper segmentation (e.g. by form_name, video_id).

For a full list of built-in event types and their meanings, see Event Types Reference.