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

Parameter	Type	Required	Description
$event_type	string	Yes	The event type name (e.g. `newsletter_signup`, `lead_submitted`, `video_play`, `custom_conversion`). Must be non-empty.
$args	array	No	Optional event data. See Optional $args keys below. Default: empty array.

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).

Key	Type	Description
session_id	string	Override session ID. Normally from current session.
ip_address	string	Override IP address. Normally from current request.
user_id	int	Override user ID. Normally current user (or 0).
page_href	string	Override page URL. Normally current page (same domain required).
event_quantity	int	Quantity (default: 1).
event_value	float	Monetary value (default: 0).
object_id	int	WordPress post/page/object ID.
object_type	string	Post type (e.g. `post`, `page`, `product`).
product_id	int	Product ID for product-related events.
variation_id	int	Variation ID for variable products.
additional_data	array	Extra key-value data; stored as JSON with the event.

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.

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 ).