Browser SDK

Utility methods

Control Browser SDK loading, readiness, diagnostics, events, and dispatch timing.

The Ferno Browser SDK follows the Segment-compatible Analytics.js API for these lifecycle and utility methods. Use them to control initialization and troubleshoot delivery without changing the events your application sends.

AnalyticsBrowser.load#

FieldRequiredTypeDescription
settingstrueAnalyticsBrowserSettingsFerno project settings, including writeKey; may include cdnSettings and plugins.
settings.writeKeytruestringFerno browser write key.
settings.cdnSettingsfalseobjectExplicit delivery settings, such as the Segment-compatible integration configuration.
settings.pluginsfalsePlugin[]Plugins to register during initialization.
optionsfalseInitOptionsInitialization options such as persistence, page-view, integration, cookie, and storage settings.

AnalyticsBrowser.load is the static form. The instance form is useful when an app must create the buffered instance before consent is known:

Call load once for an instance. Initialization loads settings and destinations, flushes calls buffered before initialization, and makes the SDK ready for dispatch. Calls such as track and page made before loading are buffered; they do not send a network request until loading starts.

For consent-gated loading, create the instance first and call load only after consent:

Use disableClientPersistence: true in options when the browser identity must not be stored. See setup and initialization for Ferno delivery settings.

analytics.ready#

FieldRequiredTypeDescription
callbackfalse(results: unknown[]) => voidRuns after registered destinations and plugins report readiness. Receives their readiness results.

ready() returns a promise that resolves after every registered destination or plugin with a ready hook has completed. The promise resolves to an array of those results. The optional callback receives the same array; it is useful when integrating with callback-oriented Analytics.js code.

Wait for readiness before work that depends on a destination or plugin being initialized:

analytics.debug#

FieldRequiredTypeDescription
toggletruebooleantrue enables development diagnostics; false disables them.

debug is chainable, so it can be configured with other SDK calls:

Keep diagnostics disabled in production unless you intentionally need them for a controlled investigation. Debug output can include operational event details; do not use it as a substitute for removing sensitive data from payloads.

analytics.on#

FieldRequiredTypeDescription
eventtruestringEvent name to observe, such as track, identify, page, group, alias, error, or a lifecycle event.
callbacktrue(...args: unknown[]) => voidListener invoked with the event's emitted payload.

on registers a listener and returns the analytics instance for chaining. Common events include the tracking methods (track, identify, page, group, and alias), error, and lifecycle events such as ready, reset, and delivery lifecycle notifications.

Keep listeners observational. Read only the fields needed by the application and never log tokens, passwords, payment data, raw form values, messages, or other sensitive content:

Register listeners before load when using the instance form; the Browser SDK buffers supported listeners until initialization.

analytics.timeout#

FieldRequiredTypeDescription
millisecondstruenumberMaximum dispatch/callback wait in milliseconds.

Set the timeout when navigation, unload, or a callback needs a different maximum wait:

The value is in milliseconds and must be numeric. A larger value gives dispatch and callback handling more time; a smaller value reduces how long browser actions wait. This setting controls SDK dispatch/callback timing. It is not a general network retry or backoff configuration; configure delivery retry behavior separately in the integration settings.