Browser SDK

Delivery strategy

Configure Ferno Browser SDK request headers, keepalive, and batching.

The Ferno Browser SDK sends browser events through the Segment.io integration to Ferno's /events endpoint. Its deliveryStrategy configuration controls how those requests are dispatched.

Configuration#

FieldRequiredTypeDescription
strategyfalse`'standard' \'batching'`
configtrueobjectFetch and batching settings for Ferno requests.
config.headersfalse`object \function`
config.keepalivefalsebooleanAllows requests to continue while the page is unloading. Defaults to false.
config.credentialsfalse`'include' \'same-origin' \
config.priorityfalse`'high' \'low' \
config.sizefalsenumberBatching event-count threshold. Defaults to 10.
config.timeoutfalsenumberBatching flush timeout in milliseconds. Defaults to 5000.
config.maxRetriesfalsenumberMaximum retries for a batched request. Defaults to 10.

Custom headers#

Add headers to Ferno requests with config.headers:

The SDK supplies the request content type and authorization headers. Custom headers are added to those defaults. If a header is generated dynamically, provide a function:

Only send non-sensitive metadata in custom headers. The Ferno endpoint and any proxy between your app and Ferno must allow the header through CORS.

Keepalive#

Set keepalive: true when events triggered immediately before navigation or page close need the browser to continue the request:

Keepalive requests share the browser's approximately 64 KB in-flight payload limit. Larger payloads can be dropped, so keepalive is disabled by default. The SDK also uses keepalive while the page is unloading for batched requests and splits oversized batches to reduce loss.

Batching#

Batching groups multiple events into one Ferno request. This reduces request count and makes retries apply to the batch as a unit.

Both size and timeout affect when a batch is sent:

  • size sends the batch when it reaches the event-count threshold. For example, size: 10 sends after 10 events.
  • timeout sends queued events after the specified number of milliseconds, even when the batch has not reached size.

Ferno batches are limited to 500 KB total, with a 32 KB limit per event. The SDK splits a batch when it approaches the total payload limit. Smaller batches or shorter timeouts reduce the amount of queued data at page close, but increase request count.

Delivery and retries#

Batching delays retries until the batch request fails. A failed batch is retried as a unit according to Ferno's HTTP retry and backoff settings. Configure those settings separately with httpConfig; deliveryStrategy.config.timeout is only the batching flush timeout.

Queued events are best-effort during browser shutdown. Keepalive, smaller batch sizes, and shorter batch timeouts can reduce loss, but no browser can guarantee delivery after a tab closes or a process is terminated.