# Breaking Changes in JavaScript SDK v3

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

## Storage and encryption

This section covers the new changes introduced in the JavaScript SDK's storage and encryption features.

### Storage prefix changes

The local storage entries prefix has been updated from `rudder` to `rudder_<write-key>`, where `<write-key>` is your JavaScript source {{< glossary_tooltip "write-key" >}}.

### Encryption updates

- Storage data encryption now uses Base64 by default.
- Existing persisted data is automatically migrated to the latest version unless specified otherwise.
- New load API options for encryption configuration are introduced:

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

{{< warning >}}
**Important storage encryption considerations**

If you have implemented the JavaScript SDK in multiple sites sharing the same top-level domain and cookies and have different major SDK versions across these sites, then RudderStack recommends the following actions:

- Consider upgrading **all** sites to the [latest v3 SDK version](https://www.npmjs.com/package/@rudderstack/analytics-js?activeTab=versions) at once.
- If that is not possible, then upgrade the older sites to the [latest version](https://www.npmjs.com/package/rudder-sdk-js) of SDK v1.1.
- If any of the above actions are not possible, then set the [`storage.encryption.version`]({{< ref "sources/event-streams/sdks/rudderstack-javascript-sdk/load-js-sdk.md#storage" >}}) parameter to `legacy` for all the sites.

See the [JavaScript SDK Migration Guide]({{< ref "sources/event-streams/sdks/rudderstack-javascript-sdk/migration-guide.md#pre-migration-checklist" >}}) for more information.
{{< /warning >}}

## Installation related changes

- The [SDK loading snippet]({{< ref "sources/event-streams/sdks/rudderstack-javascript-sdk/installation.md" >}}) is updated in v3.
- The SDK file name is changed from `rudder-analytics.min.js` to `rsa.min.js`.
- NPM package is changed from [`rudder-sdk-js`](https://www.npmjs.com/package/rudder-sdk-js) to [`@rudderstack/analytics-js`](https://www.npmjs.com/package/@rudderstack/analytics-js) to [`@rudderstack/analytics-js`](https://www.npmjs.com/package/@rudderstack/analytics-js).
- All `GET` type methods from the loading snippet (`getAnonymousId`, `getGroupTraits`, etc.) are removed. These methods were not functional before the SDK loaded, making them unnecessary. However, these APIs are available in the SDK instance once it is loaded.

## Default `page` call removed

The default `page` call is removed from the loading snippet. You must now explicitly make a `page` call, if required.

## Source configuration changes

The default source configuration host has changed from `rudderlabs.com` to `rudderstack.com`. If you're using a proxy for the source configuration host, update it to forward `https://api.rudderstack.com` instead of `https://api.rudderlabs.com`.

## Consent management updates

The consent management configuration structure is updated in v3:

{{< tabs tabTotal="2" >}}
{{% tab tabName="Previous configuration" %}}
```javascript
rudderanalytics.load(WRITE_KEY, DATA_PLANE_URL, {
  cookieConsentManager: {
    oneTrust: {
      enabled: true
    }
  }
});
```
{{% /tab %}}
{{% tab tabName="New configuration (v3)" %}}
```javascript
rudderanalytics.load(WRITE_KEY, DATA_PLANE_URL, {
  consentManagement: {
    enabled: true,
    provider: 'oneTrust'
  }
});
```
{{% /tab %}}
{{< /tabs >}}

## Client-side events filtering changes

For [Client-side Events Filtering]({{< ref "sources/event-streams/sdks/event-filtering.md" >}}):

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

## Changes in `integrations` options

The destination names in the [`integrations`]({{< ref "sources/event-streams/sdks/rudderstack-javascript-sdk/load-js-sdk.md#integrationopts" >}}) object must exactly match the names displayed in the [RudderStack 
dashboard](https://app.rudderstack.com/directory). Custom names assigned during destination setup are no longer supported.

{{< warning >}}
The SDK will ignore any destination names that don't match exactly as shown in the dashboard.
{{< /warning >}}

{{< image src="images/dashboard-guides/amplitude-destination-name-webapp.webp" >}}

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

{{< tabs tabTotal="2" >}}
{{% tab tabName="While loading the SDK" %}}

The below sample snippet loads the SDK with the **Amplitude**, **Intercom**, and **ActiveCampaign** destinations only:

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

Declaring the destination names in the `integrations` object in the following manner will **not** work anymore:

```javascript
// Incorrect usage
rudderanalytics.load(WRITE_KEY, DATA_PLANE_URL, {
  integrations: {
    All: false,
    "AM": true,
    "INTERCOM": true,
    "ACTIVE_CAMPAIGN": true
  }
});
```
{{% /tab %}}
{{% tab tabName="At event level" %}}

The following snippet highlights a sample `track` event sent to only the **Amplitude** destination:

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

Declaring the destination name in the `integrations` object in the following manner will **not** work anymore:

```javascript
// Incorrect usage - will not work
rudderanalytics.track(
  "Order Completed", {
    revenue: 30,
    currency: "USD",
    user_actual_id: 12345
  }, {
    integrations: {
      All: false,
      "AM": true
    }
  }
);
```
{{% /tab %}}
{{< /tabs >}}

## Ad blocker detection changes

- The ad blocker detection logic is updated.
- Dependency on the Google AdSense script is removed.

## Service worker

Service worker is now available as a separate package. It is published at [@rudderstack/analytics-js-service-worker](https://www.npmjs.com/package/@rudderstack/analytics-js-service-worker).

## Removed features

[Sync pixel callback]({{< ref "archive/javascript-sdk/1.1/supported-api.md#callbacks-to-common-methods" >}}) feature has been removed.

<br />