Event Batching

All VWO FME SDKs implement an advanced event batching mechanism to efficiently handle tracking for visitor events, conversion goals, and custom attributes. Instead of sending each event individually, the SDK collects them in memory and dispatches them in bulk within a single network request.

This batching approach offers several advantages:

• Performance Optimisation: Reduces the number of network calls, thereby lowering bandwidth usage and minimising latency.
• Improved Reliability: Batching makes the system more resilient during high event throughput by avoiding request flooding.
• Configurable Dispatch Triggers: Events are dispatched either when a predefined batch size is reached or after a time threshold, whichever comes first.
• Memory-Efficient Queuing: Events are queued in memory, ensuring lightweight operations with minimal overhead on the application.

Developers can configure batching behavior to match their application’s performance characteristics and tracking needs. Whether you’re using the SDK on a web, mobile, or server-side environment, event batching ensures scalable and robust data collection.

What is Event Batching?

Event Batching is a core mechanism across all VWO FME SDKs that enhances performance and scalability by aggregating multiple tracking events—such as visitors, conversions, and attribute updates—before sending them to the VWO servers.

Rather than sending each event as an individual network request, the SDK collects events over a period of time, queues them in memory, and dispatches them together in a single batched request. For example, if an application generates 4,000 events in quick succession, the SDK groups these into one or more batches based on configurable thresholds, significantly reducing the number of outbound network calls.

Key Concepts:

• Events-Level Tracking: Multiple events (user, conversion, and attributes) for the same user are batched and sent together.
• Threshold-Based Dispatching: Events are flushed when a maximum batch size is reached or after a specified time interval, whichever comes first.
• Optimized Network and Server Usage: Batching dramatically reduces API call volume, helping conserve bandwidth and decrease server load.
• Configurable Behaviour: Developers can adjust batching thresholds to suit their application's scale, responsiveness requirements, and network conditions.

This approach ensures reliable and efficient data transmission, especially in high-traffic environments where event volumes are significant.

Configuring Event Batching

VWO FME SDKs offer flexible configuration options to control how event batching behaves across different environments. During SDK initialization, developers can enable and fine-tune event batching via a configuration object (commonly named batch_event_data or equivalent, depending on the SDK language.

This configuration allows you to define when and how events—such as visitor tracking, conversions, and custom attributes—should be grouped and dispatched to the VWO servers.

Configuration Parameters:

1. events_per_request – Maximum Events per Batch
   Specifies the maximum number of events that can be included in a single batch request. Events continue to accumulate in the internal queue until this threshold is reached, triggering an immediate dispatch.
2. request_time_interval – Dispatch Interval (in seconds)
   Defines the time-based threshold for flushing events. Once the first event is queued, the SDK starts a timer. If the events_per_request limit is not met by the end of this interval, the queued events are dispatched anyway.
3. flush_callback – Post-Dispatch Hook
   An optional callback function is executed after the events are successfully (or unsuccessfully) sent to the VWO servers. The callback typically receives:
   1. error: Details of any transmission failure (if applicable).
   2. events: The list of events that were flushed in the batch.

Example Use Cases:

• On a high-traffic application, increase events_per_request to reduce API overhead.
• For low-frequency tracking, reduce request_time_interval to ensure timely dispatch.
• Use flush_callback for logging, retry logic, or triggering downstream workflows.

By customizing these options, developers gain fine-grained control over how event data flows to VWO, ensuring optimal performance, reliability, and observability across different platforms.

Example usage

require 'vwo'

# flush_callback method
def call(error, data)
    # custom implementation here
end

# Initialize VWO client
vwo_client = VWO.init({
    sdk_key: '32-alpha-numeric-sdk-key',
    account_id: '123456',
    batch_event_data: {
        events_per_request: 50, # Optional: 50 events per request (default is 100)
        request_time_interval: 60 # Optional: send events every 60 seconds (default is 600 seconds)
        flush_callback: method(:call) # Optional: callback to execute after flush
    },
})

# Call the following method only if you need to manually flush the events; otherwise, it can be ignored.
vwo_client.flush_events()

🚧

Note

• The maximum number of events that can be queued is 5000.
• The default time interval is 600 seconds (10 minutes), in case of invalid time interval is passed.

📘

Important Note

Event Timing: The timer starts when the first event is added to the queue. If the time interval expires before the event count reaches the events_per_request threshold, the events are dispatched anyway.

Manual Flushing: You can trigger the dispatch of events before the batch limit or time interval is reached by manually calling the flush_events() method.

Flushing Events Manually (Flush Events API)

In some situations, events can be sent immediately, before the batch size or time interval is reached. This can be done using the flush_events() method, which manually triggers the event dispatch.

# Call the following method only if you need to manually flush the events; otherwise, it can be ignored.
vwo_client.flush_events()

Event Batching Lifecycle in VWO FME SDKs

The VWO FME SDKs provide a structured mechanism for batching events before sending them to the VWO server. The flow below outlines how events are processed, queued, and flushed—either automatically or manually, based on configuration parameters defined during SDK initialization.

flowchart TD
    A["SDK Initialization with batch_event_data"] --> B["Event Occurs"]
    B --> C["Add to Local Batch Queue"]

    %% Automatic Flushing triggers
    C --> D1{"Flush Condition?"}
    D1 -->|"Reaches events_per_request"| E1["Send Batched Events if events_per_request events reached in the queue"]
    D1 -->|"After request_time_interval"| E2["Send Batched Events if request_time_interval is reached"]

    %% Manual Flush
    C -.->|"Manually call flush_events"| E3["Manually Flush Batched Events"]

    %% All flushes trigger callback
    E1 --> X["flush_callback(error, events)"]
    E2 --> X
    E3 --> X

    %% Assign classes
    class A,B,C,D1,E1,E2,E3 step;
    class X callback;

		%% Define styles
    classDef check fill:#bbf,stroke:#333,stroke-width:1px,color:#000

1. SDK Initialization with batch_event_data

The event batching behavior is activated by passing the batch_event_data configuration during SDK initialization. This includes:

• events_per_request: Maximum number of events per batch.
• request_time_interval: Max wait time before forcing a flush.
• flush_callback: Function called post-flush.

2. Event Occurs

Each time an event is triggered (visitor tracking, conversion, or attribute update), the SDK:

• Captures the event data.
• Adds the event to an in-memory local batch queue.

3. Batch Queue Management

As events accumulate, the SDK evaluates flushing conditions based on the following criteria:

➤ Automatic Flush Triggers

The SDK checks if it's time to flush the queued events:

• When events_per_request is reached:
  Once the number of events in the queue meets or exceeds the configured limit, the SDK immediately sends the batched request to the VWO server.
• When request_time_interval is exceeded:
  If the configured time interval passes (from the time the first event was added), the SDK flushes whatever events are present in the queue, even if the batch size hasn’t been met.

➤ Manual Flush Option

Developers can trigger a flush programmatically using a method like flush_events() (name may vary by SDK). This is useful in scenarios such as:

• App shutdown or page unload
• Test/QA scripts
• Ensuring real-time dispatch in critical flows

4. Post-Flush Callback

Regardless of how the flush was triggered (automatic or manual), the SDK invokes the flush_callback function (if provided), which receives:

• error: Any error encountered during the dispatch (e.g., network failure).
• events: The list of events successfully sent in the batch.

This allows for custom logging, error handling, or retry logic.