What's New in JavaScript SDK v3

Understand the newly introduced features in JavaScript SDK v3.

This guide details the new features introduced in JavaScript SDK v3.

Event dispatching for SDK initialized and ready phases

The SDK v3 supports dispatching two new events to document - RSA_Initialised and RSA_Ready - when it is in the initialized and ready phases respectively.

These events provide a reference to the analytics instance (analyticsInstance) whenever you want to use it to invoke any API method, for example, getUserId.

You can listen to the above events as follows:

   document.addEventListener('RSA_Initialised', function(e) {
     console.log('RSA_Initialised', e.detail.analyticsInstance);
   document.addEventListener('RSA_Ready', function(e) {
     console.log('RSA_Ready', e.detail.analyticsInstance);

You can use this feature as an alternative to the ready API method and the onLoaded load option for orchestration with JavaScript frameworks and libraries. It is useful in cases where relevant business logic is in functions that cannot be declared alongside the analytics integration or they need to be declared on a decoupled code base for some reason.

Batching in XHRQueue plugin

The JavaScript SDK v3 provides the XhrQueue plugin that leverages queueOptions to control the behavior of the persistence queue that buffers events in local storage before sending them to the data plane.

You can also send a batch of events to the data plane using the queueOptions.batch object while loading the SDK:

rudderanalytics.load(WRITE_KEY, DATA_PLANE_URL, {
  queueOptions: {
    minRetryDelay: 1000, // ms
    batch: {
      enabled: true,
      maxItems: 100,
      maxSize: 1024 * 512 // 512 KB
      flushInterval: 60000 // ms

The following table details the queueOptions.batch object parameters:

ParameterData typeDescriptionDefault value
enabledBooleanDetermines if the SDK should activate the batching functionality.false
maxItemsIntegerMaximum number of events in a batch.100
maxSizeIntegerMaximum batch payload size.512 KB (Also, the maximum configurable value)
flushIntervalIntegerMinimum interval between two batch requests.60000 ms

Note that:

  • queueOptions.batch is an optional object, meaning batching is disabled by default.
  • The SDK makes a batch request when either of the following criteria is met:
    • maxItems in a batch is reached.
    • maxSize of the batch is reached.
    • Time period of flushInterval ms has elapsed since the last batch request.


The SDK v3 exposes the following objects globally that can assist in debugging:

window.rudderAnalyticsBuildTypeDenotes the build type to load based on browser capabilities (modern or legacy).
window.RudderStackGlobalsContains some SDK application-level values, preloadBuffer (before it is consumed) and the SDK instance state per write key. You can use it to debug and see values in state at any point in time.

Questions? Contact us by email or on Slack