Event Batching

Overview

Event batching is a performance optimization technique that groups multiple events together before sending them to your analytics service. This is particularly useful when:

• You’re not using an analytics service with built-in batching (like Amplitude or Google Analytics)
• You need to reduce the number of network requests
• You want to optimize for performance at scale

Configuration

Enable batching in your tracker configuration:

const [Track, useTracker] = createTracker({
  // ... other config
  batch: {
    enable: true,
    interval: 2000,
    thresholdSize: 100,
    onFlush: (batch, isBrowserClosing) => {
      if (isBrowserClosing) {
        // Use sendBeacon for reliable delivery when browser is closing
        navigator.sendBeacon("/analytics/collect/batch", JSON.stringify(batch));
        return;
      }
 
      // Normal batch submission
      fetch("/analytics/collect/batch", {
        method: "POST",
        body: JSON.stringify(batch),
      });
    },
  },
});

Options

• enable: boolean (default: false)
  • Enables/disables batching
• interval: number (default: 3000)
  • Time in milliseconds between batch flushes
• thresholdSize: number (default: 25)
  • Maximum number of events in a batch before forcing a flush
• onFlush: (batch: Batch[], isBrowserClosing: boolean) => void | Promise<void>
  • Required when batching is enabled
  • Function called to process the batch
  • isBrowserClosing indicates if the flush was triggered by browser closure
• onError: (error: Error) => void | Promise<void>
  • Optional error handler for batch processing failures

How It Works

1. Events are collected in memory
2. The batch is flushed when either:
   • The configured interval is reached
   • The batch size reaches the threshold
   • The browser is about to close/hide

Example Flow

const [Track, useTracker] = createTracker({
  DOMEvents: {
    onClick: (clickParams, context) => {
      // Return value is what gets batched
      return {
        ...clickParams,
        ...context,
        event_type: "click",
        timestamp: new Date().getTime(),
      };
    },
  },
  batch: {
    enable: true,
    interval: 2000,
    thresholdSize: 100,
    onFlush: (batch, isBrowserClosing) => {
      // Process the batch
    },
  },
});
 
function App() {
  return (
    <Track.Provider initialContext={{ deviceId: "device-123" }}>
      <Track.Click params={{ buttonId: "submit" }}>
        <button>Submit</button>
      </Track.Click>
    </Track.Provider>
  );
}

When the button is clicked multiple times:

1. Each click runs the onClick handler
2. The return value from each handler is added to the batch queue
3. After 2 seconds (or when threshold is reached), onFlush is called with all collected events

Browser Closing Behavior

When the browser is closing, you should use navigator.sendBeacon to ensure reliable delivery:

onFlush: (batch, isBrowserClosing) => {
  if (isBrowserClosing) {
    navigator.sendBeacon("/analytics/collect/batch", JSON.stringify(batch));
    return;
  }
 
  // Normal operation
  fetch("/analytics/collect/batch", {
    method: "POST",
    body: JSON.stringify(batch),
  });
};

Important Notes

1. Only the return values from event handlers are batched, not the handlers themselves
2. Each event in the batch maintains its original parameters and context
3. Events are processed in order, maintaining the sequence of user actions
4. Use navigator.sendBeacon for browser closing scenarios to ensure delivery