Function: wpdai_track_custom_event

Record a custom analytics event from PHP (backend). Core params (session_id, ip_address, user_id, page_href) are set automatically from the current session when not provided; pass them in $args only when you need to override (e.g. server-side or headless context).

Description

Use this function when you want to track a custom event server-side—for example after form processing, in a hook, shortcode, or template. Only $event_type is required; all other fields are optional. Core params are filled from the current Alpha Insights session and request when omitted. Events are written to the same table as frontend and built-in events (wp_wpd_ai_woocommerce_events) and respect the same settings (event tracking enabled, user exclusions, rate limiting).

Location

File: includes/wpd-functions.php

Line: ~1350

Function Signature

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

Parameters

Optional $args keys

Core params are set automatically from the current session when not provided. Override them only when you have your own session/request context (e.g. webhook, background job).

Return Value

Type: array

Description: Result from the event insertion. Keys:

• success (bool) — Whether the event was inserted.
• message (string) — Human-readable message.
• code (string) — Code for the outcome (e.g. success, invalid_event_type, tracking_disabled, admin_skip, no_landing_page, rate_limit_exceeded).
• rows_inserted (int) — Number of rows inserted (0 or 1).

Example Usage

Basic usage

wpdai_track_custom_event( 'newsletter_signup' );

With additional data

wpdai_track_custom_event( 'lead_submitted', array(
    'object_id'       => 0,
    'object_type'     => 'lead_form',
    'additional_data' => array(
        'lead_id'   => $lead_id,
        'form_name' => 'Contact',
    ),
) );

In a hook (e.g. after form processing)

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

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

    if ( ! empty( $result['success'] ) ) {
        // Event recorded
    }
}

With value and object context

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',
    ),
) );

Checking the result

$result = wpdai_track_custom_event( 'custom_conversion', array( 'additional_data' => array( 'campaign' => 'summer' ) ) );

if ( ! empty( $result['success'] ) ) {
    // Event was inserted
} else {
    // Log or handle: $result['code'], $result['message']
}

Notes

• 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 success and code to handle failures.
• Use a consistent naming convention for $event_type (e.g. snake_case) so custom events are easy to filter in reports.

Related

• Tracking Custom Events — Full guide for custom events (JavaScript and PHP) in Website Traffic documentation.
• For direct low-level access (full control over the event payload), use WPDAI_WooCommerce_Event_Tracking::get_instance()->insert_event( $data ).