Version: Latest (3.0)1.1

JavaScript SDK Migration Guide

This guide lists the steps to update your RudderStack JavaScript SDK from the older versions.

Before migrating, make sure to go through the Breaking Changes in the SDK v3.

Migration considerations

Note the following while migrating your SDK to the latest version:

• RudderStack stores all its cookies in the top-level domain of your site by default unless you’ve configured to change the domain. So, if you have implemented the SDK in multiple sites that share the same top-level domain and cookies are shared between these sites, then you must use the same encryption version (preferably v3) for all the sites.

  For example, if xyz.test.com uses the latest JavaScript SDK (v3) and abc.test.com uses a legacy SDK version (v1.1 or below), then you should set the storage load API option as follows to avoid corrupting the storage data for the other sites:

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

If you have any special needs and have implemented different major versions of the SDK (not recommended) across your sites, you need to set the encryption version to legacy. This way the SDK 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.

• The new SDK will migrate the existing (older) cookies to the new encryption technique for a seamless transition by default unless you have:

  • Explicitly configured the storage.migrate load API option to false, or
  • Specified the plugins load API option to exclude the StorageMigrator plugin.

• As the data encryption technique has changed, you must update your decryption logic if you were previously accessing the data directly from the storage. However, reading the cookies directly is not recommended.

CDN

Change the SDK installation snippet. Then, 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.

For more information, see the following guides:

• CDN installation method for installing the SDK snippet.
• Setup for serving Javascript SDK if you are using your own domain to proxy the SDK or route the events.

NPM

The NPM package based on the latest JavaScript SDK architecture is available here.

The latest SDK’s NPM package is published as @rudderstack/analytics-js instead of rudder-sdk-js.

You can use any of the following options to update the SDK using NPM:

npm i @rudderstack/analytics-js

"dependencies": {
  "@rudderstack/analytics-js": "^3.x.x"
}

Questions? Contact us by email or on Slack