User.com REST API Docs

# Tracking 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 User.com backend. Unlike page views, these events are not automatic; they must be triggered programmatically in response to user 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 User.com 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 > App 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.

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('User.com SDK not loaded yet');
        }
    }
}, false);

# Solution 2: Google Tag Manager

If you are using Google Tag Manager, avoid firing User.com 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 user's timeline in User.com. The event should appear instantly.

← Tracking Product Events →