{"componentChunkName":"component---src-templates-markdown-template-jsx","path":"/developers/client-sdks/web/upgrade-to-version-3/","result":{"data":{"pageMetadata":{"title":"Upgrade to Version 3 of the SDK","path":"/developers/client-sdks/web/upgrade-to-version-3/","sourceCode":null,"metadataParent":{"title":"Web","path":"/developers/client-sdks/web/","sourceCode":"https://github.com/mParticle/mparticle-sdk-javascript","hasVersionPicker":null,"metadataChildren":[{"title":"Initialization","path":"/developers/client-sdks/web/initialization/","order":2,"label":null},{"title":"Configuration","path":"/developers/client-sdks/web/configuration/","order":3,"label":null},{"title":"Content Security Policy","path":"/developers/client-sdks/web/content-security-policy/","order":3,"label":null},{"title":"Event Tracking","path":"/developers/client-sdks/web/event-tracking/","order":4,"label":null},{"title":"User Attributes","path":"/developers/client-sdks/web/users/","order":5,"label":null},{"title":"IDSync","path":"/developers/client-sdks/web/idsync/","order":6,"label":null},{"title":"Page View Tracking","path":"/developers/client-sdks/web/screen-tracking/","order":7,"label":null},{"title":"Commerce Events","path":"/developers/client-sdks/web/commerce-tracking/","order":8,"label":null},{"title":"Location Tracking","path":"/developers/client-sdks/web/location/","order":9,"label":null},{"title":"Media","path":"/developers/client-sdks/web/media/","order":10,"label":null},{"title":"Kits","path":"/developers/client-sdks/web/kits/","order":11,"label":null},{"title":"Application State and Session Management","path":"/developers/client-sdks/web/session-management/","order":12,"label":null},{"title":"Data Privacy Controls","path":"/developers/client-sdks/web/data-privacy-controls/","order":13,"label":null},{"title":"Error Tracking","path":"/developers/client-sdks/web/error-and-exception-tracking/","order":14,"label":null},{"title":"Opt Out","path":"/developers/client-sdks/web/opt-out/","order":14,"label":null},{"title":"Custom Logger","path":"/developers/client-sdks/web/custom-logger/","order":15,"label":null},{"title":"Persistence","path":"/developers/client-sdks/web/persistence/","order":16,"label":null},{"title":"Native Web Views","path":"/developers/client-sdks/web/native-webviews/","order":17,"label":null},{"title":"Self-Hosting","path":"/developers/client-sdks/web/self-hosting/","order":18,"label":null},{"title":"Multiple Instances","path":"/developers/client-sdks/web/multiple-instances/","order":19,"label":null},{"title":"Web SDK via Google Tag Manager","path":"/developers/client-sdks/web/gtm-templates/","order":20,"label":null},{"title":"Preventing Blocked HTTP Traffic with CNAME","path":"/developers/client-sdks/web/prevent-blocked-http-traffic/","order":21,"label":null},{"title":"Facebook Instant Articles","path":"/developers/client-sdks/web/facebook-instant-articles/","order":22,"label":null},{"title":"Troubleshooting the Web SDK","path":"/developers/client-sdks/web/troubleshooting/","order":23,"label":null},{"title":"Browser Compatibility","path":"/developers/client-sdks/web/browser-compatibility/","order":24,"label":null},{"title":"Linting Data Plans","path":"/developers/client-sdks/web/linting/","order":25,"label":null},{"title":"API Reference","path":"/developers/client-sdks/web/api-reference/","order":26,"label":null},{"title":"Upgrade to Version 3 of the SDK","path":"/developers/client-sdks/web/upgrade-to-version-3/","order":28,"label":null},{"title":null,"path":"/developers/client-sdks/web/changelog/","order":null,"label":null}],"metadataParent":{"title":"Client SDKs","path":"/developers/client-sdks/","metadataChildren":[{"title":"Alexa","path":"/developers/client-sdks/alexa/","order":1,"label":null},{"title":".NET MAUI","path":"/developers/client-sdks/maui/","order":null,"label":null},{"title":"AMP","path":"/developers/client-sdks/amp/","order":null,"label":null},{"title":"Android","path":"/developers/client-sdks/android/","order":null,"label":null},{"title":"Cordova","path":"/developers/client-sdks/cordova/","order":null,"label":null},{"title":"Direct Url Routing","path":"/developers/client-sdks/direct-url-routing/","order":null,"label":null},{"title":"Flutter","path":"/developers/client-sdks/flutter/","order":null,"label":null},{"title":"iOS","path":"/developers/client-sdks/ios/","order":null,"label":null},{"title":"React Native","path":"/developers/client-sdks/react-native/","order":null,"label":null},{"title":"Roku","path":"/developers/client-sdks/roku/","order":null,"label":null},{"title":"Unity","path":"/developers/client-sdks/unity/","order":null,"label":null},{"title":"Web","path":"/developers/client-sdks/web/","order":null,"label":null},{"title":"Xbox","path":"/developers/client-sdks/uwp/","order":null,"label":null}],"metadataParent":{"title":"Developers","path":"/developers/","metadataChildren":[{"title":"API Credential Management","path":"/developers/credential-management/","order":null,"label":null},{"title":"API References","path":"/developers/apis/","order":null,"label":null},{"title":"Client SDKs","path":"/developers/client-sdks/","order":null,"label":null},{"title":"Guides","path":"/developers/guides/","order":null,"label":null},{"title":"Media SDKs","path":"/developers/media-sdks/","order":null,"label":null},{"title":"Quickstart","path":"/developers/quickstart/","order":null,"label":null},{"title":"Server SDKs","path":"/developers/server-sdks/","order":null,"label":null},{"title":"The Developer's Guided Journey to mParticle","path":"/developers/developersjourney/","order":null,"label":null},{"title":"Tools","path":"/developers/tools/","order":null,"label":null}],"metadataParent":null}}}},"markdownRemark":{"html":"

Version 3 of the mParticle Web SDK is a major release that contains breaking changes from version 2.x. It removes several long-deprecated APIs and changes how kits are versioned and published to npm. Ignore this section if you are implementing the mParticle Web SDK for the first time and don’t need to upgrade from an older version.

\n

For the full changelog, see 3.0.0 changelog on GitHub.

\n

\n \n \n \n \n \n \n \n Summary of Changes

\n\n

\n \n \n \n \n \n \n \n Upgrading via Snippet (CDN)

\n

Version 3 is loaded with a new snippet. Rather than editing your existing snippet in place, replace it entirely:

\n
    \n
  1. Remove the v2 snippet from your pages or templates.
    2. \n
  2. Copy the latest snippet from the initialization guide and paste it into the <head> tag of every page of your web app, keeping any mParticle.config options you had customized in your v2 snippet.
    3. \n
  3. In the snippet, replace REPLACE WITH API KEY with your web API key. First-party (CNAME) domain instructions don’t change - see the docs for instructions there.
    4. \n
\n

As with v2, kits for any integrations you have enabled in the mParticle UI are included automatically, so no kit-related action is needed. However, the removed APIs below still apply — audit your code for usage of removed methods before you switch.

\n

\n \n \n \n \n \n \n \n Upgrading via npm (Self-Hosting)

\n

\n \n \n \n \n \n \n \n Update the Core SDK

\n

Update @mparticle/web-sdk to version 3:

\n
npm install @mparticle/web-sdk@^3.0.0
\n

\n \n \n \n \n \n \n \n Update All Kits Together

\n

In v2, each kit was versioned independently, so kit versions had no relationship to the core SDK version or to each other. In v3, all mParticle-hosted kits share the core SDK’s version number, and every kit is republished with each core SDK release, even if the kit’s code did not change.

\n

This means that when you upgrade the core SDK, you should upgrade all of your mParticle kit packages to the same version at the same time. As an example:

\n
npm install @mparticle/web-sdk@^3.0.0 \\\n  @mparticle/web-braze-kit-6@^3.0.0 \\\n  @mparticle/web-google-analytics-4-client-kit@^3.0.0 \\\n  @mparticle/web-onetrust-kit@^3.0.0
\n

Mixing a v3 core SDK with v2-era kit packages (or vice versa) is not supported. v3 kits declare a peerDependency on @mparticle/web-sdk@^3.0.0, so npm will warn you if your versions are misaligned.

\n

\n \n \n \n \n \n \n \n Kit Package Name Changes

\n

Kits that support multiple major versions of a partner SDK now include the partner SDK’s major version in the package name. Choose the package that matches the partner SDK major version you use:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Integrationv2 Packagev3 Package
Braze@mparticle/web-braze-kit @ 3.x@mparticle/web-braze-kit-3 (Braze Web SDK 3.x)
Braze@mparticle/web-braze-kit @ 4.x@mparticle/web-braze-kit-4 (Braze Web SDK 4.x)
Braze@mparticle/web-braze-kit @ 5.x@mparticle/web-braze-kit-5 (Braze Web SDK 5.x)
Braze@mparticle/web-braze-kit @ 6.x@mparticle/web-braze-kit-6 (Braze Web SDK 6.x)
\n

In v2, the Braze kit encoded the Braze Web SDK major version in its own package version (for example, @mparticle/web-braze-kit@6.x wrapped Braze Web SDK 6.x). Because all v3 kits now share the core SDK’s version number, the partner SDK version moved into the package name instead.

\n

All other kit packages keep their existing names, but need to be installed with their respective version 3 instead.

\n

\n \n \n \n \n \n \n \n Removed APIs

\n

The following deprecated APIs have been removed in v3. All of them have logged deprecation warnings since earlier v2 releases.

\n

\n \n \n \n \n \n \n \n Cart API

\n

The Cart API was deprecated in v2 and has been removed. This includes:

\n\n

Log cart activity with logProductAction instead:

\n
// Before (v2)\nmParticle.eCommerce.Cart.add(product, true);\nmParticle.eCommerce.Cart.remove(product, true);\n\n// After (v3)\nmParticle.eCommerce.logProductAction(mParticle.ProductActionType.AddToCart, [product]);\nmParticle.eCommerce.logProductAction(mParticle.ProductActionType.RemoveFromCart, [product]);
\n

\n \n \n \n \n \n \n \n logCheckout and logRefund

\n

logCheckout and logRefund have been removed. Use logProductAction with the corresponding ProductActionType:

\n
// Before (v2)\nmParticle.eCommerce.logCheckout(step, option, attrs);\nmParticle.eCommerce.logRefund(transactionAttributes, product);\n\n// After (v3)\nmParticle.eCommerce.logProductAction(mParticle.ProductActionType.Checkout, products, attrs, customFlags, transactionAttributes);\nmParticle.eCommerce.logProductAction(mParticle.ProductActionType.Refund, products, attrs, customFlags, transactionAttributes);
\n

\n \n \n \n \n \n \n \n removeCCPAState

\n

removeCCPAState has been removed. Use removeCCPAConsentState instead:

\n
// Before (v2)\nconsentState.removeCCPAState();\n\n// After (v3) - Both methods existed on v2, but removeCCPAState was removed.\nconsentState.removeCCPAConsentState();
\n

\n \n \n \n \n \n \n \n Upgrade Checklist

\n","frontmatter":{"title":"Upgrade to Version 3 of the SDK","order":28,"seoTitle":null,"seoDescription":null},"parent":{"__typename":"File","modifiedTime":"September 14, 2026"}}},"pageContext":{"slug":"/developers/client-sdks/web/upgrade-to-version-3/"}},"staticQueryHashes":["2950460867"]}