Custom events

Event tracking allows you to capture specific behavioral actions—such as button clicks, file downloads, or exit intents—and trigger automations or score updates in real-time.

Introduction

The userengage() function is the primary method for sending behavioral data to the Positive User backend. Unlike page views, these events are not automatic; they must be triggered programmatically in response to contact interactions.

Method signature

userengage(eventName, attributes)

• eventName (String, Required): The identifier for the action. Must start with the prefix event..
• attributes (Object, Optional): A key-value object containing metadata about the event.

Capabilities & scope

Naming conventions

All event names passed to the function must be prefixed with event..

• Correct: userengage('event.download_pdf')
• Incorrect: userengage('download_pdf') — This will fail to register as an event.

Attribute typing & auto-creation

You do not strictly need to pre-define events in the Positive User dashboard before sending them. However, strict data typing is enforced.

Important: If you send an attribute that does not exist in your dashboard, the system will automatically create it with a String data type. To ensure attributes are stored as Numbers, Booleans, or Dates, we strongly recommend defining them in Settings > Workspace Settings > Event attributes before implementation.

Supported data types

Type	JS Example	Notes
String	"premium"	Default type if undefined.
Number	199.00	Supports integers and floats.
Boolean	true
Datetime	"2023-11-25"	Use ISO 8601 or YYYY-MM-DD.
JSON	{ x: 10, y: 200 }	Pass a nested object directly.

Implementation

Basic tracking

For simple interactions where no extra context is needed.

// Triggering a simple event
userengage('event.popup_closed');

Rich tracking (with attributes)

For complex actions, pass an object as the second argument. This example demonstrates tracking an "Exit Intent" with multiple data types.

userengage('event.exit_intent', {
    // String: Where they were
    current_section: "pricing_table",
    
    // Number: How many seconds they spent before trying to leave
    seconds_on_page: 45,
    
    // Boolean: Did they copy text to clipboard?
    has_copied_text: true,
    
    // JSON: Exact mouse coordinates (Nested Object)
    mouse_position: {
        x: 1240,
        y: 15
    }
});

Timing & safety

The userengage function is only available after the widget.js script has fully loaded.

The Race Condition

If you attempt to call userengage() immediately on page load (e.g., inside a <script> tag in your <head>), the browser may execute it before the SDK has initialized.

• Result: The browser throws a ReferenceError: userengage is not defined.
• Data Loss: The event is not sent.

Solution 1: Defensive coding (Recommended)

Always check if the function exists before calling it.

// Example: Tracking an exit intent safely
document.addEventListener("mouseleave", function(e) {
    if (e.clientY < 0) {
        if (typeof window.userengage === 'function') {
            userengage('event.exit_intent');
        } else {
            console.warn('Positive User SDK not loaded yet');
        }
    }
}, false);

Solution 2: Google Tag Manager

If you are using Google Tag Manager, avoid firing Positive User events on "Page View". Instead, use Trigger Groups or wait for the widget to signal readiness.

• Strategy: Configure your Custom HTML tags to fire only when the window.userengage object is detected, or use a "Window Loaded" trigger to ensure all scripts have finished executing.

Verification

To confirm your events are being tracked successfully:

1. Console Check: Open your browser's Developer Tools (Console) and manually fire a test event:

   userengage('event.test_console_fire');

2. Network Activity: Look at the Network tab for a request to the /api/event/ endpoint.
   • Status: 200 OK indicates success.
   • Payload: Verify the JSON payload matches your attributes.
3. Dashboard: Go to the specific contact's timeline in Positive User. The event should appear instantly.