Configure Event Batching

All SDKs send impression events to VWO servers for visitors and conversions tracking. Events are tracked in real-time to i.e. as soon as tracking-data APIs are hit and the data could be seen in VWO Campaigns Reports.
There are scenarios, depending on the implementation and requirements, when a certain number of events need to be collected over a period of time, batched, and relayed to VWO server in a single request. In this case, VWO SDKs offer a way to configure event batching at the time of instantiating the SDK.

Benefits

1. Less number of network requests for the same number of impression events.
2. Total size of transmitted data is reduced by extracting common properties in every event and sending them once per batch network request.

📘

Please Note:

Without event batching, impression events are sent to VWO in real-time to be get reflected instantaneously in the campaign reports.

With event batching, the campaign reports will only be updated once the batch events request is sent from your server to VWO.

Real-time(Serial) vs Batch Events

In a normal scenario, all events are dispatched as soon as the event happens.
In the case of Event Batching, impression events are collected over a period of time, combined, and sent in a single network request.
Event Batching, as opposed to real-time events, requires a setting to decide when the events should be flushed and sent via a network request.

Configure Event Batching

VWO SDKs provide two ways to configure when events should be sent to VWO servers. This can be done only while instantiating the SDK by passing batchEvents key along with one or both of the following keys.

1. eventsPerRequest - number of events that should be batched together and sent to VWO server in a single network request. Until this number is not reached, all events will be queued.
2. requestTimeInterval - Send a request to VWO server after batching events only when the oldest event in the queue has lived for the specified time interval.

📘

Setting the options

If only eventsPerRequest is provided then requestTimeInterval is set to a default value of 600(10 minutes).

If only requestTimeInterval is provided then eventsPerRequest is set to a default value of 100 events

If both eventsPerRequest and requestTimeInterval are specified, SDK will send a batch request based on which one happens first. For example, if the events count reaches the limit first then the batch request will be sent and the timer will reset whereas, if the time elapsed even before filling in the required events, a batch request will be sent, the queue will be emptied, and the timer will reset.

👍

Request Time Interval

If requestTimeInterval is passed or the default value is used in case of not passing, the timer would only start when the first event would come. This is to ensure the time range is properly used with uneven distribution of events over a period of time. For example, the server starts at Xth time and the first event occurs at (X + 5)th time, the timer will start from (X + 5)th time and will be cleared once the queue is flushed.
Again, when the new event will occur, then only the timer would be registered to prevent unnecessary processing and proper utilization of the time-interval window.

🚧

Either of eventsPerRequest or requestTimeInterval is required for event batching to work.
Otherwise, an impression event would be sent in real-time.

Which events are batched?

Events that are responsible for tracking metrics for VWO application i.e. visitors, conversions, and custom dimensions.

Following are the APIs which will push an event into the batch queue:

1. Activate - tracking visitors for both A/B and Feature Test campaigns
2. Is Feature Enabled - tracking visitors for only for Feature Test campaign
3. Track - tracking conversions for A/B and Feature Test campaigns
4. Push - tracking custom dimensions being pushed for post-segmentation capabilities

What happens when the limit is reached?

📘

Maximum Limits

The maximum events that can be queued at a time is 5000. The maximum payload size is 10 MB.

If the above-mentioned limits exceed in any case, VWO server will reject the request responding with status code 413 and message Payload size too large. Try with a smaller events number by reducing eventsPerRequest or setting a smaller interval via requestTimeInterval.

VWO SDKs also provide a functionality to call a function upon successful/failure batch network request to VWO server. You can pass flushCallback in batchEvents config at the time of launching the SDK.

var settingsFile = await vwoSdk.getSettingsFile(accountId, sdkKey);

vwoSdk.lanuch({
  settingsFile: settingsFile,
  batchEvents: {
    eventsPerRequest: 1000, // specify the number of events
    flushCallback: (err, events) => console.log(err, events)
  }
});

import vwo

settings_file = vwo.get_settings_file(account_id, sdk_key)

vwo.launch(settings_file,
            batch_events = {
              'events_per_request': 5, # specify the number of events
              'request_time_interval': 60, # time in seconds
              'flush_callback': flush_callback
            }
)

BatchEventData batchData = new BatchEventData();
  batchData.setEventsPerRequest(1000);
  batchData.setRequestTimeInterval(1000);
  batchData.setFlushCallback(new FlushInterface() {
    @Override
    public void onFlush(String s, JsonNode objectNode) {}
  });

  String settingsFile = VWOHelper.getSettingsFile(accountId, sdkKey);
  VWO vwoInstance = VWO.launch(settingsFile).withBatchEvents(batchData).build();

Manually flush events

Since VWO SDKs queue the events and are sent in a network request only upon meeting the configurational options limit passed in batchEvents config, there might be cases when you would need to manually flush the queue so that data could be sync with VWO server to be reflected in the respective Campaigns' reports.

This is also helpful in cases where your server abruptly or gracefully gets closed. Ensure to flush the events to VWO so that there would be no data loss on server termination.

VWO SDKs have introduced a new API on the client's instance. The name of the API is flushEvents .
It makes sure to flush the queue irrespective of the batchEvents configuration so that events could be successfully reached to VWO server without any data loss. Any timers associated would also be cleared.

flushEvents API

var settingsFile = await vwoSdk.getSettingsFile(accountId, sdkKey);

var vwoClientInstance = vwoSdk.launch({
  settingsFile: settingsFile,
  batchEvents: {
    eventsPerRequest: 1000, // specify the number of events
    flushCallback: (err, events) => console.log(err, events)
  }
});

// Example usage of flushEvents API
// Node.js events - SIGINT(ctr-c), SIGTERM otherwise
process.on('SIGINT', async () => {
  console.log('SIGINT signal received.');
  vwoClientInstance.flushEvents().then(data => {
    console.log('data', data); // if anything to do with data
    process.exit(0); // gracefully shutdown
  });
});

import vwo

settings_file = vwo.get_settings_file(account_id, sdk_key)

vwo.launch(settings_file,
            batch_events = {
              'events_per_request': 5, # specify the number of events
              'request_time_interval': 60, # time in seconds
              'flush_callback': flush_callback
            }
)

@app.route("/flush-events")
def flush_events():
    # mode is used to specify the nature of batch call.
    # Can be 'sync' or 'async', defaults to 'sync'
    mode = request.args.get("mode")
    vwo_client_instance.flush_events(mode = mode)
    return jsonify({'success': True})

import com.vwo.VWO;
VWO vwoInstance;

String settingsFile = VWOHelper.getSettingsFile(Config.accountId, Config.sdkKey);
this.vwoInstance = VWO.launch(settingsFile)
  .withSdkKey(Config.sdkKey)
  .withPollingInterval(pollingTime)
  .withBatchEvents(VWOHelper.getBatchingData())
  .build();

@GetMapping(value = "/flushEvents")
public String flush(Model model) {
  boolean isEventsQueueFlushed = false;
  try {
    isEventsQueueFlushed = this.vwoInstance.flushEvents();
  }
  catch (Exception e) {
    e.printStackTrace();
  }
  finally {}

  return "success";
}

Supported SDKs

🚧

JavaScript SDK

The port of Node.js SDK i.e. JavaScript SDK, which runs on the client-side does not support event-batching as everything happens in the context of a single-user and the events are not much. The browsers also handle multiple calls gracefully.