Skip to main content

Track Instant Events

The setInstantEventProperties method is used to send events immediately to Zeotap, bypassing the normal queuing and batching mechanism. This is ideal for critical events that require real-time tracking.

Why use it?

  • Immediate Delivery: Events are sent instantly without waiting for batch processing.
  • Critical Events: Perfect for tracking urgent events like errors, crashes, or time-sensitive actions.
  • Real-time Analytics: Ensures important events are captured immediately even if the app closes.
When to Use

Use instant events sparingly for critical events only, as they bypass performance optimizations like batching and may impact network usage.

Syntax​

import { setInstantEventProperties } from 'zeo-collect';

setInstantEventProperties(eventName, eventProperties, callback)

Parameters​

ParameterTypeRequiredDescription
eventNameStringYesThe name of the event to track immediately
eventPropertiesObjectNoKey-value pairs of event properties
callbackFunctionNoCallback function to handle response

Usage Examples​

Instant Event Name Only​

If you only need to track the event name without additional properties for critical events:

import { setInstantEventProperties } from 'zeo-collect';

// Track instant event with name only
setInstantEventProperties("app_crash");

The payload with instant event name only:

Instant event name only in payload
    "events": [
        {
            "event": {
                "eventName": "app_crash",
                "eventTimestamp": 1745959356443
            },
            "user": {
                "zi": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"
            },
            "page": { /* ... */ },
            "version": "1.3.8"
        }
    ]

Basic Instant Event Tracking​

import { setInstantEventProperties } from 'zeo-collect';

// Track a critical event with properties
setInstantEventProperties("critical_error", {
    error_type: "network_failure",
    error_code: "ERR_CONN_TIMEOUT",
    error_message: "Connection timeout after 30 seconds",
    user_action: "checkout_attempt"
});

The payload with instant event that is sent immediately:

Instant event with properties in payload
    "events": [
        {
            "event": {
                "eventName": "critical_error",
                "error_type": "network_failure",
                "error_code": "ERR_CONN_TIMEOUT",
                "error_message": "Connection timeout after 30 seconds",
                "user_action": "checkout_attempt",
                "eventTimestamp": 1745959356443
            },
            "user": {
                "zi": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"
            },
            "page": { /* ... */ },
            "version": "1.3.8"
        }
    ]

Instant Event with Callback​

import { setInstantEventProperties } from 'zeo-collect';

setInstantEventProperties("payment_failed", {
    payment_id: "PAY-12345",
    failure_reason: "insufficient_funds",
    amount: 99.99,
    currency: "USD",
    retry_attempt: 2
}, (response) => {
    console.log("Instant event tracked:", response);
    // Handle success/error response
});

Performance Impact​

Network Usage​

  • Instant events create immediate network requests
  • Consider batching multiple instant events if they occur simultaneously
  • Monitor data usage in your analytics

Battery Life​

  • Frequent instant events can impact battery life
  • Use only for truly critical events
  • Consider user's network conditions

For more examples and integration patterns, see our Examples Guide.

Last updated on