Version: Latest (3.0)1.1

Load JavaScript SDK

You can load the JavaScript SDK using the load API method to track and send events from your website to RudderStack.

rudderanalytics.load(WRITE_KEY, DATA_PLANE_URL, [loadOptions]);

Replace the write keyThe write key (or source write key) is a unique identifier for your source. RudderStack uses this key to send events from a source to the specified destination. and data plane URLThe data plane URL is the location where events are routed and sent to the RudderStack backend for processing. You can find this URL in the home page of your RudderStack dashboard. with their actual values in the snippets (wherever applicable) throughout this guide.

Loading options

You can use the loadOptions object in the above load call to define various options while loading the SDK. It includes the following optional parameters:

The following load API options are deprecated in the latest JavaScript SDK in favour of the storage.cookie option:

• setCookieDomain
• sameSiteCookie
• secureCookie

The following snippet highlights some basic and commonly configured load options. Note that it does not include all the load options.

{
  logLevel: 'DEBUG',
  integrations: {
    All: true,
    "Google Analytics 4": false
  },
  queueOptions: {
    maxItems: 200,
    maxAttempts: 15
  },
  useBeacon: true,
  beaconQueueOptions: {
    maxItems: 50,
    flushInterval: 60000 // 1 minute
  },
  consentManagement: {
    enabled: true,
    provider: 'oneTrust'
  },
  onLoaded: () => {
    console.log('RudderStack JavaScript SDK loaded successfully')
  },
  uaChTrackLevel: "full",
  sendAdblockPage: true
}

The following sections contain the detailed definitions and usage of some of the above parameters:

Integration options

You can use the integrations object to filter events to selective web device mode destinations in the following scenarios:

• While loading the JavaScript SDK via the load API.
• Sending events to specific destinations at the event level.

The integrations object in the load API only controls the loading of the device mode destinations. The data is not propagated to the individual event payloads automatically.

To use the globally-defined integration options at the event level, set the useGlobalIntegrationsConfigInEvents option of the load API to true.

The structure of the integrations object is shown:

rudderanalytics.load(WRITE_KEY, DATA_PLANE_URL, {
  integrations: {
    All: boolean, // default true
    <Destination1>: boolean, //or object
    <Destination2>: boolean // or object
    ...
  }
});

The following table describes the above (optional) parameters in detail:

{
All: false, 
Amplitude: true
}

The destination name in the integrations object should match the name exactly as displayed in the RudderStack dashboard. It should not be the name that you assigned to the destination while setting it up in RudderStack.

The below sample snippet sends the event data only to the Amplitude and Intercom destinations:

rudderanalytics.load(WRITE_KEY, DATA_PLANE_URL, {
  integrations: {
    All: false,
    "Amplitude": true,
    "Intercom": true
  }
});

The below snippet sends the event data to all the destinations except Amplitude:

rudderanalytics.load(WRITE_KEY, DATA_PLANE_URL, {
  integrations: {
    All: true,
    "Amplitude": false
  }
});

The below snippet highlights a case where an object is sent instead of a Boolean. In this case, RudderStack sends an identify event to Mailjet to remove the user named Alex Keener from the list ID 13314el9Z:

rudderanalytics.identify('1hKOmRA4el9Z', {
      firstName: 'Alex',
      lastName: 'Keener',
      email: "alex@example.com"
    },
      externalId: [{
        type: "listId",
        id: "13314el9Z"
      }],
      integrations: {
        Mailjet: {
          Action: "remove"
        }
      }
    );

Use globally-defined integration options at event level

You can use the useGlobalIntegrationsConfigInEvents option to use the integrations object of the load API at the event level if it is not present in the event.

For example, if the integrations object is defined in the load method and the useGlobalIntegrationsConfigInEvents option is set to true:

rudderanalytics.load(WRITE_KEY, DATA_PLANE_URL, {
  integrations: {
    All: true,
    "Google Analytics": false,
    ...
  },
  useGlobalIntegrationsConfigInEvents: true,
  // other load options
});

Case 1: integrations option is present at the event level:

rudderanalytics.track(
  "Order Completed", {
    revenue: 30,
    currency: "USD",
    user_actual_id: 12345
  }, {
    integrations: {
      All: true,
      Amplitude: false
    },
  },
  () => {
    console.log("track call");
  }
);

In this case, the JavaScript SDK uses the integrations option from the track event.

The SDK gives precedence to the integrations object defined at the event level over the globally-defined integrations object.

Case 2: integrations option is not present at the event level:

rudderanalytics.track(
  "Order Completed", {
    revenue: 30,
    currency: "USD",
    user_actual_id: 12345
  }, {},
  () => {
    console.log("track call");
  }
);

In this case, the SDK uses the integrations option from the load API.

Get source configuration

The getSourceConfig function returns a custom configuration that can be used in place of your open source control plane’s dashboard configuration:

rudderanalytics.load(WRITE_KEY, DATA_PLANE_URL, {
  getSourceConfig: function() {
    return {
      // custom configuration
    };
  },
  // other load options
});

Queue options

The queueOpts object contains the options to control the behavior of the persistence queue that buffers the events before sending them to RudderStack. Its structure is defined as follows:

{
  maxRetryDelay: 360000,
  minRetryDelay: 1000,
  backoffFactor: 2,
  backoffJitter: 0,
  maxAttempts: 10,
  maxItems: 100,
  batch: {
    enabled: true,
    maxItems: 100,
    maxSize: 512 * 1024, // 512 KB
    flushInterval: 60000 // In ms
  },
}

The following table describes the above integer type (optional) parameters in detail:

Batch request options

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.

Session options

The SessionOpts object contains the options related to the SDK’s automatic session tracking behavior. Refer to the Session Tracking guide for more information. Its structure is defined as follows:

Consent management options

Once a user provides the consent, you can load the JavaScript SDK and enable the OneTrust integration via the consentManagement object:

rudderanalytics.load(WRITE_KEY, DATA_PLANE_URL, {
  consentManagement: {
    enabled: true,
    provider: "oneTrust"
  },
  // other options
});

Anonymous ID options

You can use the anonymousIdOptions object to automatically capture the anonymous ID from a source and set it as RudderStack’s anonymousId.

For example, if you are migrating from a particular source and want to retain its anonymous ID, you can enable the anonymousIdOptions to set the source’s anonymous ID as the anonymousId in RudderStack.

The structure of anonymousIdOptions is defined as follows:

rudderanalytics.load(WRITE_KEY, DATA_PLANE_URL, {
  anonymousIdOptions: {
    autoCapture: {
      enabled: true,
      source: "segment"
    }
  }
});

The following table describes the above (required) parameters in detail:

Note that:

• If the RudderStack anonymousId is already set in your browser, anonymousIdOptions will not take effect.
• You can call the reset API to clear the persisted anonymous ID and force the SDK to generate a new ID when the next tracking API is called (irrespective of whether anonymousIdOptions is enabled or disabled). However, if the anonymousIdOptions object is enabled and the SDK is loaded again (as a result of webpage reload, navigate to a different webpage, etc.), the setAnonymousId call will trigger automatically and the anonymous ID for the specific source will be set again as the RudderStack anonymousId.

Configure information present in context

You can use the uaChTrackLevel option to configure the information a user should get in the context object regarding the client hints. The JavaScript SDK fetches this information using the user-agent client hints API. It can take the below values:

• none: Specifies that uaChTrackLevel field is absent in the context object.
• default: Specifies that uaChTrackLevel field is present in the context object and contains an object similar to the one below:

{
  "brands": [{
    "brand": "Chromium",
    "version": "110"
  }, {
    "brand": "Not A(Brand",
    "version": "24"
  }, {
    "brand": "Google Chrome",
    "version": "110"
  }],
  "mobile": false,
  "platform": "macOS"
}

• full: Specifies that uaChTrackLevel field is present in the context object and contains an object similar to the one below:

{
  "architecture": "arm",
  "bitness": "64",
  "brands": [{
    "brand": "Chromium",
    "version": "110"
  }, {
    "brand": "Not A(Brand",
    "version": "24"
  }, {
    "brand": "Google Chrome",
    "version": "110"
  }],
  "fullVersionList": [{
    "brand": "Chromium",
    "version": "110.0.5481.77"
  }, {
    "brand": "Not A(Brand",
    "version": "24.0.0.0"
  }, {
    "brand": "Google Chrome",
    "version": "110.0.5481.77"
  }],
  "mobile": false,
  "model": "",
  "platform": "macOS",
  "platformVersion": "13.1.0",
  "uaFullVersion": "110.0.5481.77",
  "wow64": false
}

The onLoaded callback function

The onLoaded callback function takes the rudderanalytics instance as an argument and executes after the JavaScript SDK loads and before the native device-mode destination SDKs are loaded.

rudderanalytics.load(WRITE_KEY, DATA_PLANE_URL, {
  onLoaded: function(rudderanalytics) {
    console.log("All set!");
  }
});

Destination queue options

The destinationsQueueOptions object controls the behavior of the in-memory queue that buffers events before sending them to the device mode destinations. Its structure is defined as follows:

rudderanalytics.load(WRITE_KEY, DATA_PLANE_URL, {
  destinationsQueueOptions: {
    maxItems: 100
  }
});

Set external anonymous ID cookie name

You can use this option to specify the cookie name in cases where the user has set a cookie for the SDK to fetch the external anonymous ID and use it further as the RudderStack’s anonymousId.

If you provide a cookie name that does not exist, the SDK either uses the existing anonymousId or generates a new one.

Note that the external anonymousId is fetched only once while loading the SDK and any changes to the anonymousId cookie mid-session is not reflected in the events. To modify the anonymousId stored by RudderStack in such cases, use the setAnonymousId method.

Optimize timers behavior

The JavaScript SDK internally uses timers to continuously interact with the local storage. These timers acknowledge the local storage status and reclaim any stale event queues. They run at a set frequency optimizing their performance.

Generally, these timers do not impact your webpage. However, if you still feel that your webpage’s performance is degraded by any CPU or memory spikes, you can configure the value of timerScaleFactor parameter. It is an integer with the minimum and maximum values as 1 (default value) and 10 respectively. The higher the value, the slower the timers run - reducing their impact on the page, if any.

Plugins

Plugins are JavaScript SDK features that you can optionally load on demand.

If you wish to use only a subset of the SDK features, you can explicitly specify the plugins in the plugins option while loading the SDK.

For example, if you do not want the external anonymous ID, Google Linker and error reporting features, you can provide an array of plugin names excluding those plugins. A sample snippet highlighting how to set the plugins load option in this scenario:

plugins: ["BeaconQueue", 
          "DeviceModeDestinations", 
          "NativeDestinationQueue",
          "StorageEncryptionLegacy",
          "StorageEncryption",
          "StorageMigrator",
          "XhrQueue",
          "OneTrustConsentManager",
          "KetchConsentManager"
         ]

If you set the plugins option and exclude certain plugins from the list (for example, OneTrustConsentManager), setting the associated options while loading the SDK (for example, consentManagement.provider to oneTrust) will have no effect.

If you do not specify the plugins option while loading the JavaScript SDK, then RudderStack considers all plugins mentioned in the above table by default.

Once the list of plugins is determined, the SDK automatically loads a subset of them based on your load options, browser capabilities, and source configuration.

For example, if you set consentManagement.provider to ketch, then the SDK will not load OneTrustConsentManager plugin by default.

Lazyloading plugins

For older browsers and users intentionally using the legacy Javascript SDK, RudderStack bundles the plugins with the core SDK. However, for modern browsers, the SDK lazy loads the plugins as multiple small chunks. These chunks are very small in size and loaded with the website parallelly.

The SDK’s bundling tool uses a package that supports Module Federation to bundle each feature into separate code chunks that can have interdependency among themselves. These chunks act as containers and can expose and consume code between them, creating a single, unified application. These chunks or plugins are then uploaded into CDN.

Depending on the load options, browser capabilities, and source configuration, RudderStack fetches these plugins from the remote location at runtime when the SDK loads.

Storage

You can use the storage load option to configure different storage-specific features like encryption and migration.

rudderanalytics.load(WRITE_KEY, DATA_PLANE_URL, {
  storage: {
    encryption: {
      version: "v3" / "legacy"
    },
    migrate: true / false,
    cookie: {
      maxage: 31536000 * 1000, // 1 year
      path: "/",
      domain: "example.com",
      samesite: "Lax",
      secure: true / false
    }
  }
});

If you set version to legacy, then you must also load the StorageEncryptionLegacy plugin. For v3, you must load the StorageEncryption plugin.

Similarly, if you do not set migrate to false, then you must also load the StorageMigrator plugin.

Note that:

• If you access the SDK persisted data directly from the cookie or local storage, you must update the custom decryption logic.
• All sites under the same top-level domain must use the same encryption version. For example, if xyz.test.com uses the latest JavaScript SDK and abc.test.com uses a legacy SDK version (v1.1 or below), then you should set the storage load option as follows:

rudderanalytics.load(WRITE_KEY, DATA_PLANE_URL, {
  storage: {
    encryption: {
      version: "legacy"
    }
  },
  // other load options
});

• Migrating all your subdomain sites to use SDK v3 is recommended.

Cookie settings

The cookie object contains the configurable options for your cookie. All parameters in this object are optional.

The configuration provided in these cookie options overrides any other cookie settings.

Configure persistent data storage

While loading the JavaScript SDK, you can specify the information to store (userId, anonymousId, session information, etc.) and whether to store it in your browser’s cookies, local storage, in-memory storage, or not store it at all (fully anonymous tracking).

See Configure Persistent Data Storage guide for more information.

Consent management

You can integrate the JavaScript SDK with leading consent management solutions like OneTrust and Ketch or set up a custom consent management solution.

In addition, you can also configure the pre-consent behavior - either tracking users as fully anonymous, tracking only their sessions, or tracking with anonymousId as their identifier. This minimizes any data loss related to attribution, acquisition, and the overall user journey.

Use the consentManagement load option to set your consent management preferences while loading the SDK, as shown:

rudderanalytics.load(WRITE_KEY, DATA_PLANE_URL, {
  consentManagement: {
    enabled: true,
    provider: 'oneTrust' // `ketch`
  }
});

Load SDK for self-hosted control plane

If you are self-hosting the control plane using the Control Plane Lite utility, the load call should be made as below:

rudderanalytics.load(WRITE_KEY, DATA_PLANE_URL, {
  configUrl: CONTROL_PLANE_URL,
});

Allowlist RudderStack domain

If you are using RudderStack’s CDN for the SDK content, add the following (minimum) content security policy (CSP) header configuration to load the JavaScript SDK without any errors:

A content security policy (CSP) adds an extra layer of protection from any type of cross-site scripting, clickjacking, and data injection attacks.

<meta http-equiv="Content-Security-Policy" content="script-src 'self' 'unsafe-inline' https: //cdn.rudderlabs.com/ https://cdn.rudderstack.com/;">

If you don’t want to allow unsafe inline and use the CDN package with its loading snippet, use nonce attribute to the script tag for the loading snippet:

<meta http-equiv="Content-Security-Policy" content="script-src 'self' 'nonce-rAnd0m' https: //cdn.rudderlabs.com/ https://cdn.rudderstack.com/;">

If you use the NPM package, no inline loading snippet is required:

<meta http-equiv="Content-Security-Policy" content="script-src 'self' https: //cdn.rudderlabs.com/ https://cdn.rudderstack.com/;">

Device mode destinations

While using the JavaScript SDK with destinations that support device mode, you might need to allowlist the domain from where the destination SDK loads in your content security policy (CSP).

See the specific destination’s documentation to obtain the domain to be allowlisted. For example, Braze.

Tracking user sessions

By default, the JavaScript SDK automatically tracks the user sessions. This means that RudderStack automatically determines the start and end of a user session depending on the inactivity time configured in the SDK (default time is 30 minutes).

rudderanalytics.load(WRITE_KEY, DATA_PLANE_URL, {
  sessions: {
    autoTrack: true,
    timeout: 10 * 60 * 1000,  // 10 min in milliseconds
  },
  ...<otherLoadOptions>
});

To disable automatic session tracking, you can set the load option autoTrack to false.

For more information on the user sessions and how to track them using the JavaScript SDK, refer to the Session Tracking guide.

Send events using Beacon

The JavaScript SDK lets you send the event payloads using the XHR (XMLHttpRequest) API (default) or Beacon browser utility.

There are two advantages of using the Beacon utility to send your event payload:

• The events delivery request is executed even when the page unloads, leading to no loss of data.
• The Beacon requests are optimized so that the browser waits until the CPU load is lower or until the network is free before making the actual requests, leading to better website performance.

The Beacon queue maintained by the browsers limits the total size of the elements present in the queue at any point and peaks at 64 KB.

See Event delivery and retry mechanism to help you decide whether to use Beacon to send your events.

Workflow

The Beacon browser utility asynchronously sends a small amount of data over HTTP to the RudderStack server. To send the SDK events using this utility, set the useBeacon field in the load() call options to true.

The SDK internally uses a queue (BeaconQueueOpts) to buffer the events and send it through the Beacon utility in batches. The queue options can be configured as shown below:

{
  maxItems: 10, 
  flushQueueInterval: 600000 // In ms
}

The following table describes the above integer type parameters in detail:

The JavaScript SDK flushes the Beacon events queue if the total size of the payload exceeds 64 KB before even reaching the maxItems or flushQueueInterval criteria.

Event delivery and retry mechanism

This section highlights some important points which will help you choose whether to use Beacon for sending your event payloads:

• The requests sent from the SDK using the Beacon utility only push the events to the browser’s Beacon queue. Further, it depends on the browser’s engine to send these events from the queue. Hence, RudderStack cannot guarantee if any events get discarded due to any 5xx or other network-related errors (request timed out, end resource unavailable, etc.).

If event delivery and retry is an important requirement for your website, using the XHR API of the JavaScript SDK is highly recommended. RudderStack retries event delivery based on the status codes and other errors.

• The Beacon queue maintained by the browsers limits the total size of the elements present in the queue at any point and peaks at 64 KB. Therefore, you cannot send high-frequency hits from the main thread in one go, as the Beacon queue cannot take up cycles to dequeue itself.

Questions? Contact us by email or on Slack