Filter: wpd_ai_event_data_before_insertion

Adjust or enrich Alpha Insights event payloads immediately before they are written to the events database table.

Description

This filter fires after Alpha Insights finishes normalizing and sanitizing an event payload but before the final insert statement runs. It gives developers one last chance to tweak values, append metadata, or enforce store-specific policies on tracked events. Typical use cases include injecting derived metrics, mapping product identifiers, or attaching contextual data gathered elsewhere in your stack.

Location

File: includes/classes/WPD_WooCommerce_Events.php

Method: WPD_WooCommerce_Events::insert_event()

Line: ~354

Parameters

Return

Type: array

Description: The payload to persist. Always return the complete array, even if you only modify one value.

Common Use Cases

• Append structured metadata (campaign, channel, coupon) to additional_data
• Override event_value or event_quantity using business rules
• Map transient identifiers (session, lead, CRM IDs) into reserved columns
• Normalize URLs, product IDs, or object references from headless frontends
• Prevent noisy events by short-circuiting when required fields are missing

Example Usage

Add Campaign Metadata

add_filter( 'wpd_ai_event_data_before_insertion', 'ai_attach_campaign_metadata' );
function ai_attach_campaign_metadata( $data )
{
    $metadata = array(
        'campaign' => isset( $_COOKIE['ai_campaign'] ) ? sanitize_text_field( $_COOKIE['ai_campaign'] ) : '',
        'utm_source' => isset( $_GET['utm_source'] ) ? sanitize_text_field( $_GET['utm_source'] ) : '',
        'utm_medium' => isset( $_GET['utm_medium'] ) ? sanitize_text_field( $_GET['utm_medium'] ) : '',
    );
    if ( ! empty( $metadata['campaign'] ) || ! empty( $metadata['utm_source'] ) )
    {
        $existing = isset( $data['additional_data'] ) && ! empty( $data['additional_data'] )
            ? json_decode( $data['additional_data'], true )
            : array();
        $data['additional_data'] = wp_json_encode( array_merge( $existing, $metadata ) );
    }
    return $data;
}

Enforce Minimum Event Value

add_filter( 'wpd_ai_event_data_before_insertion', 'ai_floor_event_value' );
function ai_floor_event_value( $data )
{
    if ( isset( $data['event_value'] ) && $data['event_value'] 

Skip Unsupported Events

add_filter( 'wpd_ai_event_data_before_insertion', 'ai_skip_untrusted_events' );
function ai_skip_untrusted_events( $data )
{
    if ( empty( $data['page_href'] ) || false === strpos( $data['page_href'], 'yourstore.com' ) )
    {
        // Return early by throwing a WP_Error or logging & returning untouched data.
        // To fully halt insertion, hook into WPD_WooCommerce_Events earlier and stop the process.
        $data['additional_data'] = wp_json_encode( array( 'discarded_event' => true ) );
    }
    return $data;
}

Best Practices

• Always return an array; the database interactor expects a complete payload.
• Use standard WordPress sanitization functions for any new data you add.
• Preserve required keys (session_id, page_href, event_type, etc.) to avoid database errors.
• Keep the filter lightweight—avoid remote HTTP calls or long-running tasks.
• Log adjustments when debugging, but remove noisy logging in production.

Security Considerations

• Never trust raw input; sanitize and validate before updating the payload.
• Guard against cross-site scripting by using sanitize_text_field, absint, floatval, etc.
• When storing structured metadata, use wp_json_encode to avoid invalid JSON.
• Do not expose sensitive user data in additional_data without encryption or consent.

Related Filters

• wpd_ai_order_payment_gateway_cost_default_value – Customize payment cost defaults.
• wpd_ai_custom_order_cost_default_value – Control custom order cost defaults.

Related Classes

• WPD_WooCommerce_Events – Captures and stores storefront events.
• WPD_Database_Interactor – Handles reads/writes to Alpha Insights tables.