Version: Latest (3.0)1.1

Breaking Changes in JavaScript SDK v3

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

Storage and encryption

• The local storage entries prefix for the data plane events queue has changed from rudder to rudder_<write-key>, where <write-key> is your JavaScript source 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. .

• Storage data encryption is changed to Base64 by default.

  • The existing persisted data is migrated to the latest version by default unless otherwise specified by the user.
  • New load API options are introduced to set the encryption version and migration choice:

  storage: {
    migrate: true,
    encryption: {
        version: 'v3',
      }
  }
  

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.

Installation

• 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 rudderlabs.com to rudderstack.com. If you were previously forwarding the source configuration host, you must proxy https://api.rudderstack.com instead of https://api.rudderlabs.com.

See How to Use Custom Domains for more information.

Consent management

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.

Integration options

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 JavaScript SDK ignores any other format of the name specified in the integrations object.

The following examples highlight the correct and incorrect declaration of the destination names within the integrations object:

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

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

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

rudderanalytics.track(
  "Order Completed", {
    revenue: 30,
    currency: "USD",
    user_actual_id: 12345
  }, {
    integrations: {
      All: false,
      "AM": true
    }
  }
);

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

• Service worker is now a separate package and will be published here.
• Sync pixel callback feature is removed.

Questions? Contact us by email or on Slack