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

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