JavaScript SDK v3 migration guide

Migrate your RudderStack JavaScript SDK from older versions to v3.

This guide lists the steps to migrate your RudderStack JavaScript SDK from older versions to the latest SDK v3. It also covers some common migration scenarios depending on your SDK installation method.

Migrate to JavaScript SDK v3

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

CDN

  1. Change the SDK installation and loading snippet.
  2. Use the new storage load option to auto-migrate your persisted user data. See Storage for more information on this load option.
rudderanalytics.load("<write-key>", "<data-plane-url>", {
  storage: {
    migrate: true
  }
});

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 will need this URL to configure sources. with their actual values.

info

Note that:

  • If the persisted data is directly accessed 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 JavaScript SDK v3 and abc.test.com uses a legacy SDK version (v1.1), 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.

NPM

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

info
The latest SDK v3 uses the @rudderstack/analytics-js package instead of rudder-sdk-js.

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

  • Install the v3 package using the below command:
npm i @rudderstack/analytics-js
  • Manually modify the package.json file and runnpm install:
"dependencies": {
  "@rudderstack/analytics-js": "^3.0.0-beta.x"
}

Then, use the new storage load option to auto-migrate your persisted user data. See Storage for more information on this load option.

rudderanalytics.load("<write-key>", "<data-plane-url>", {
  storage: {
    migrate: true
  }
});

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 will need this URL to configure sources. with their actual values.

info

Note that:

  • If the persisted data is directly accessed 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 JavaScript SDK v3 and abc.test.com uses a legacy SDK version (v1.1), 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.

Migration scenarios

This section covers detailed steps for migrating to JavaScript SDK v3 depending on how you installed JavaScript SDK.

Forwarded/proxied RudderStack CDN

The following steps assume that you are using AWS CloudFront to forward or proxy the RudderStack CDN. See Custom domains for more information.

warning
For JavaScript SDK v3, the default source configuration host has changed from rudderlabs.com to rudderstack.com. This means you must proxy https://api.rudderstack.com instead of https://api.rudderlabs.com.
  1. Go to Behaviors and verify that the sub-path /beta/* is not configured to be blocked in any way. This is required to ensure the core SDK and destination SDKs are properly forwarded.
  2. Update the sdkBaseUrl in the loading snippet. Change the default URL from:
var sdkBaseUrl = "https://cdn.rudderlabs.com/beta/3.0.0-beta";

to:

var sdkBaseUrl = "https://<subdomain>.<yourdomain>.com/beta/3.0.0-beta";

Self-hosted JavaScript SDK

To migrate your self-hosted JavaScript SDK to v3, follow any of these options based on your folder structure. See Host your JavaScript SDK in CDN/Storage for details.

Default structure

In this structure, there should be two directories - modern and legacy under the base directory path. The following files and folders should be present inside these two folders:

  • rsa.min.js
  • js-integrations: Device mode destination SDKs are located in this directory.
  • plugins: Plugins are located in this directory.
Recommended directory structure for self-hosting RudderStack JavaScript SDK v3

Then, update the sdkBaseUrl in the loading snippet. Change the default URL from:

var sdkBaseUrl = "https://cdn.rudderlabs.com/beta/3.0.0-beta";

to:

var sdkBaseUrl = "https://<subdomain>.<yourdomain>.com/<path-to-sdk-base-directory>";

Destination SDKs located elsewhere

If the file name of your self-hosted JavaScript SDK is rsa.min.js but the destination SDKs are not located next to the core SDK file under the js-integrations directory, then update the loading snippet to include destSDKBaseURL load option:

window.rudderanalytics.load("<write-key>", "<data-plane-url>", {
  destSDKBaseURL: "https://<subdomain>.<yourdomain>.com/<path-to-integration-sdks-directory>"
});

Plugins located elsewhere

If the file name of your self-hosted JavaScript SDK is rsa.min.js but the plugins are not located next to the core SDK file under the js-integrations directory, then update the loading snippet to include destSDKBaseURL load option:

window.rudderanalytics.load("<write-key>", "<data-plane-url>", {
  pluginsSDKBaseURL: "https://<subdomain>.<yourdomain>.com/<path-to-plugins-directory>"
});

Other scenarios

If your JavaScript SDK file name is not rsa.min.js and the destination SDKs, plugins, or both are not located under the js-integrations/plugins directory, then update the loading snippet as follows:

Instead of the default SDK file name (rsa.min.js), use the custom file name:

var sdkName = "<custom-sdk-file-name>.min.js";

For this scenario, you must use the two load options destSDKBaseURL and pluginsSDKBaseURL to correctly load the SDK, destination SDKs, and plugins:

window.rudderanalytics.load("<write-key>", "<data-plane-url>", {
  destSDKBaseURL: "https://<subdomain>.<yourdomain>.com/<path-to-integration-sdks-directory>",
  pluginsSDKBaseURL: "https://<subdomain>.<yourdomain>.com/<path-to-plugins-directory>"
});

Questions? Contact us by email or on Slack