Breaking Changes in JavaScript SDK v3

Understand the breaking changes in JavaScript SDK v3.

This guide lists the breaking changes introduced in JavaScript SDK v3.

Storage and encryption


It is recommended to use the same storage encryption version, preferably v3, across all your sites that share the same top-level domain.

If you have any special needs and have implemented different SDK major versions across your sites, you need to set the encryption version to legacy. This way the SDK v3 will continue to use the same encryption technique as the older SDK versions so that your subdomain sites using those legacy SDK versions are not impacted at all.

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

See Migration considerations for more information.


  • The SDK loading snippet has changed.
  • The file name is changed from rudder-analytics.min.js to rsa.min.js.
  • The NPM package is changed from rudder-sdk-js to @rudderstack/analytics-js.
  • All the GET type of methods (getAnonymousId, getGroupTraits, and so on) have been removed from the loading snippet.
The above GET methods will not yield anything before the SDK is loaded. Hence, it does not make sense to buffer those calls and replay them later.

No page call in loading snippet

The default page call embedded at the end of the loading snippet has been removed. So, you need to explicitly make a page call if required.

Source configuration URL

The default source configuration host has changed from to If you were previously forwarding the source configuration host, you must proxy instead of

See How to Use Custom Domains for more information.

In JavaScript SDK v3, the load API option used for configuring consent management has changed.

Previously, you could specify the consent management options for integrating OneTrust as below:

rudderanalytics.load(WRITE_KEY, DATA_PLANE_URL, {
  cookieConsentManager: {
    oneTrust: {
      enabled: true

The above snippet notifies the SDK to retrieve consent data from the OneTrust SDK loaded on your web page.

In SDK v3, cookieConsentManager is replaced with consentManagement. Also, the object structure for configuring the consent management options is changed. The new options are shown:

rudderanalytics.load(WRITE_KEY, DATA_PLANE_URL, {
  consentManagement: {
    enabled: true,
    provider: 'oneTrust'

Client-side events filtering

For client-side events filtering:

  • Empty and non-string event names are not allowlisted anymore.
  • Event name comparison is case-sensitive.

Ad blocker detection

This may not exactly be a breaking change - the ad blocker detection logic is updated. The SDK does not use the Google AdSense script anymore.

Other changes

Questions? Contact us by email or on Slack