Event Batching | Documentation

Analytics events often arrive in bursts: page views, button clicks, screen changes, lifecycle events, errors, notification events, and product actions can all happen within a few seconds. Sending each one as a separate network request works, but it adds overhead for users and for your application.

Flash Analytics batching solves that at the SDK layer. The SDK keeps a small local queue, sends events together to /track/batch, and the API processes each event through the same reliable path used by normal /track calls.

The short version

Batch events to reduce network overhead. Flash Analytics still treats every item as its own analytics event, preserving event time, sessions, profiles, billing counters, bot checks, geo enrichment, and downstream ingestion behavior.

Implementation safeguards

Batching is implemented as a small delivery layer around the existing Track API, not as a delayed analytics pipeline. The SDK queues events locally, stamps each event with the time it happened, and flushes the queue to /track/batch. The API then processes every item through the same handler used by individual /track calls.

Race conditions are avoided: flush operations are guarded so size-based flushes, timeout flushes, lifecycle flushes, and manual flushes do not drain the same queue at the same time. This prevents duplicate sends and keeps failed items safely in the queue.
Events do not wait forever for a full batch: the SDK flushes when the batch reaches the configured size or when the timeout expires. A user does not need to trigger 10 events before analytics are released.
Journey timing stays intact: events are timestamped when they are queued, not when the batch request reaches the server. This keeps time-to-convert, journey flow, and session timelines close to the real user experience.

Why batching is useful

Fewer network requests

Send nearby analytics events together instead of opening a request for every click, page view, screen view, or custom event.

Better for mobile and busy apps

Reduce browser request pressure, mobile radio wakeups, and client-side overhead during high-volume user activity.

Original event time is preserved

Events are timestamped when they happen, not when the batch is delivered, so journeys and time-based reports stay accurate.

Built-in retry and fallback

If a batch cannot be delivered, supported SDKs can fall back to individual track requests so one failed batch does not hide every event.

Same trusted pipeline

Batched events still use the normal Track API processing path for session logic, profile enrichment, bot checks, geo lookup, billing, and downstream ingestion.

Bounded by design

SDKs and the API both cap batch size at 100 events, keeping payloads predictable and safe for production traffic.

How it works

Enable batching in the SDK

You choose batching explicitly, so existing tracking behavior does not change unless you turn it on.

The SDK queues events locally

Track, identify, increment, and decrement calls can be queued with metadata that records when each event actually happened.

The queue flushes by size or time

The SDK sends a batch when it reaches the configured size or when the flush timeout expires.

The API processes each event normally

The batch endpoint reuses the same Track API handler, so reporting, sessions, enrichment, and ingestion stay consistent.

Recommended defaults

Flash Analytics starts with conservative defaults that work for most web and mobile applications. You can tune the batch size and timeout later if your app has unusually high event volume.

Setting	What it means
Opt-in behavior	Batching is disabled until you enable it in the SDK.
Default batch size	10 events.
Default flush timeout	5000 ms.
Maximum batch size	100 events, enforced by both SDK and API.
Flush triggers	The SDK flushes when the queue reaches the size limit or the timeout expires.
Lifecycle handling	Web flushes on page hide. React Native flushes on app background. Native SDKs expose manual flush controls.

Enable batching

JavaScript-family SDKs use deliveryStrategy. This gives you control over batch size, timeout, and fallback behavior.

Web, Next.js, Astro, and Node-style SDKsTypeScript

const analytics = new FlashAnalytics({
  appId: 'PROJECT_CLIENT_ID',
  onSessionUpdated(session) {
    console.log(session.id);
  },
  deliveryStrategy: {
    strategy: 'batching',
    config: {
      size: 10,
      timeout: 5000,
      fallbackToIndividual: true,
    },
  },
});

When a batch response includes a session ID, the SDK updates the same session cache used by immediate tracking. You can read it with getSession(), or subscribe with onSessionUpdatedwhen your app needs the value through a callback.

Native SDKs expose the same concept with platform-friendly option names.

Android KotlinKotlin

FlashAnalyticsOptions(
  appId = "PROJECT_CLIENT_ID",
  batchEnable = true,
  batchSize = 10,
  batchTimeoutMs = 5_000L,
)

SwiftSwift

FlashAnalyticsOptions(
  appId: "PROJECT_CLIENT_ID",
  batchEnable: true,
  batchSize: 10,
  batchTimeoutMs: 5000
)

Why Flash Analytics batching is different

Batching is not a separate import path or a second analytics system. It is a delivery optimization around the same first-party Track API pipeline your app already uses.

This matters because journey and time-based analysis is a core Flash Analytics theme. Unlike tools such as Mixpanel or Amplitude, where batching is often discussed mainly as a transport optimization and time journey charts may be absent or less central to the product experience, Flash Analytics treats journey timing as a first-class requirement. Batching is designed to improve delivery efficiency without making journey charts misleading.

Correct event order: reports use the event timestamp captured when the SDK queued the event.
Session continuity: batched events keep the same session and profile behavior as immediate events. Session data returned from a batch flush updates getSession() and triggers onSessionUpdated.
Practical reliability: SDKs handle page hide, app backgrounding, local persistence, retry, and fallback paths.
Transparent limits: batches are capped at 100 events, preventing oversized payloads from a bad configuration.

When to use it

Enable batching when your product sends frequent events, runs on mobile, captures lifecycle or notification events, or tracks interactions during busy screens such as checkout, onboarding, dashboards, editors, or games.

Keep immediate tracking for low-volume flows

If your app only sends a few events per session, immediate delivery is still fine. Batching is best when request volume, mobile reliability, or page lifecycle delivery starts to matter.

Related guides

Track Events

Send your first product events to Flash Analytics.

SDKs

Choose the SDK for your web, server, or mobile application.

How Tracking Works

Understand the event pipeline, identity model, and session logic.

Sessions

Learn how Flash Analytics keeps visit-level reporting consistent.

For platform-specific setup, open the SDK documentation and choose the SDK your app uses.