mParticle Web SDK

Hello! This is the public repo of the mParticle Web SDK. We've built the mParticle platform to take a new approach to web and mobile app data and the platform has grown to support 300+ integrations including analytics, data warehouses, and marketing automation. mParticle is designed to serve as the connector between all of these services - check out our site, or hit us at developers@mparticle.com to learn more.

Documentation

Fully detailed documentation and other information about mParticle web SDK can be found at our doc site here

Include and Initialize the SDK

There are two ways to initialize the SDK, either via a script tag, or you can bundle the SDK via NPM. A summary of steps for both are available below, but you should review the detailed documentation for the script tag and self hosting on the mParticle docs site.

Option 1. Load mParticle via Script Tag

To integrate the SDK add the following snippet to your site after customizing mParticle.config, ideally in the <head> element. Replace YOUR_API_KEY with the API key for your mParticle Web workspace.

This snippet pre-populates method stubs for much of the public SDK API, allowing immediate reference to these APIs as the SDK loads.

<script type="text/javascript">

//configure the SDK
window.mParticle = {
    config: {
        isDevelopmentMode: true,
        identifyRequest: {
            userIdentities: {
                email: 'email@example.com',
                customerid: '123456',
            },
        },
        identityCallback: function(result) {
            // Do something once an identity call has been made.
            // For more information, see https://docs.mparticle.com/developers/sdk/web/idsync/#sdk-initialization-and-identify
            console.log(result);
        },
        dataPlan: {
           planId: 'my_plan_id',
           planVersion: 2
        }
    },
};

//load the SDK
(function(e){window.mParticle=window.mParticle||{};window.mParticle.EventType={Unknown:0,Navigation:1,Location:2,Search:3,Transaction:4,UserContent:5,UserPreference:6,Social:7,Other:8,Media:9};window.mParticle.eCommerce={Cart:{}};window.mParticle.Identity={};window.mParticle.Rokt={};window.mParticle.config=window.mParticle.config||{};window.mParticle.config.rq=[];window.mParticle.config.snippetVersion=2.8;window.mParticle.ready=function(e){window.mParticle.config.rq.push(e)};var t=["endSession","logError","logBaseEvent","logEvent","logForm","logLink","logPageView","setSessionAttribute","setAppName","setAppVersion","setOptOut","setPosition","startNewSession","startTrackingLocation","stopTrackingLocation"];var i=["setCurrencyCode","logCheckout"];var n=["identify","login","logout","modify"];var o=["selectPlacements","hashAttributes","hashSha256","setExtensionData","use","getVersion","terminate"];t.forEach(function(e){window.mParticle[e]=r(e)});i.forEach(function(e){window.mParticle.eCommerce[e]=r(e,"eCommerce")});n.forEach(function(e){window.mParticle.Identity[e]=r(e,"Identity")});o.forEach(function(e){window.mParticle.Rokt[e]=r(e,"Rokt")});function r(t,i){return function(){if(i){t=i+"."+t}var e=Array.prototype.slice.call(arguments);e.unshift(t);window.mParticle.config.rq.push(e)}}var a,c,s=window.mParticle.config,l=s.isDevelopmentMode?1:0,w="?env="+l,d=window.mParticle.config.dataPlan;if(d){a=d.planId;c=d.planVersion;if(a){if(c&&(c<1||c>1e3)){c=null}w+="&plan_id="+a+(c?"&plan_version="+c:"")}}var m=window.mParticle.config.versions;var f=[];if(m){Object.keys(m).forEach(function(e){f.push(e+"="+m[e])})}var p=document.createElement("script");p.type="text/javascript";p.async=true;p.src=("https:"==document.location.protocol?"https://jssdkcdns":"http://jssdkcdn")+".mparticle.com/js/v2/"+e+"/mparticle.js"+w+"&"+f.join("&");var P=document.getElementsByTagName("script")[0];P.parentNode.insertBefore(p,P)})("REPLACE WITH API KEY");

You can then log events, for example, as follows:

mParticle.logEvent('Play Movie', mParticle.EventType.Navigation, {
    movie_length: '127 minutes',
    rating: 'PG',
});

Option 2. Self host mParticle via NPM

1. Add the SDK via NPM

In your root project directory, add the SDK to your package.json:

npm install @mparticle/web-sdk

2. Customize and Initialize the SDK

// index.js
import mParticle from '@mparticle/web-sdk';

let mParticleConfig = {
    isDevelopmentMode: true,
    identifyRequest: {
        userIdentities: {
            email: 'email@example.com',
            customerid: '123456',
        },
    },
    identityCallback: myIdentityCallback,
    dataPlan: {
        planId: 'my_plan_id',
        planVersion: 2,
    },
};
mParticle.init('REPLACE WITH API KEY', mParticleConfig);

You can then log events, for example, as follows:

mParticle.logEvent('Play Movie', mParticle.EventType.Navigation, {
    movie_length: '127 minutes',
    rating: 'PG',
});

Creating an Integration

If you configure mParticle via a snippet tag, the Web SDK is able to automatically include, initialize, and delegate API calls to 3rd-party SDKs. Otherwise you will install them via npm. For more instructions on installing via npm, view the documentation.

If you would like to add your company as a new Javascript integration, reference the following integrations as examples:

Contributing

See CONTRIBUTING.md.

The test script will run all tests using Karma and ChromeHeadless, and Firefox by default. To run tests using a different browser, use the command:

$ BROWSER=[browserBrand] npm run testBrowser

where browserBrand can be another browser such as Edge or IE.

Development Notes

This package comes with the NPM package pre-commit, which will run ESLint when you try to commit.

Three-step release process (maintainers)

Releases have separate v2 and v3 tracks. In GitHub Actions, choose the track-specific branch from the Use workflow from dropdown and run these workflows in order:

Staging Release - Step 1: Prepare CDN Pre-Release, Publish NPM (staging-step-1.yml): select staging for track=v2, or v3-staging for track=v3. This workflow builds and tests the track, creates and merges a generated release branch, runs semantic-release, and publishes the npm release. Before a new v3 release can advance, every existing kit next tag must match the core SDK's current next version. The one-time 3.0.0 bootstrap permits all kit tags to be absent so the first synchronized release can establish them. After building the target version, Step 1 also packs and registry-preflights all kit artifacts before publishing core. It then checks out the immutable release tag, publishes all packages in kits/publish-matrix.json sequentially, and verifies that the core SDK and every kit have the expected version, artifact integrity, and npm dist-tag. A rerun skips an existing kit only when its artifact is identical. dryRun=true previews the merge and semantic-release result without creating a branch or publishing; dryRun=false creates/pushes the release branch and publishes. If core publishes but kit publication cannot finish, rerun Step 1 from v3-staging with track=v3, dryRun=false, and resumeKitReleaseTag set to the exact Step 1 tag. Recovery validates that immutable tag and resumes kits without republishing core.
Staging Release - Step 2: Publish SDK Release to Release Order Branch (staging-step-2.yml, optional): select master for v2 or main for v3. The source-ref guard accepts either master or main, but use the track's matching trunk. For releaseTag, enter the exact Git tag created by the successful Step 1 run (for example, v2.80.0 or v3.0.1). Choose release-order-a, -b, or -c as releaseOrderBranch. For v3, that logical choice maps to the corresponding v3-release-order-* branch. dryRun=true validates the exact candidate and fast-forward without pushing; dryRun=false promotes it.
Staging Release - Step 3: Release to CDN and Synchronize Branches (staging-step-3.yml): select master for v2 or main for v3 (the source-ref guard accepts either). For releaseTag, enter the same exact Git tag created by the successful Step 1 run. The workflow verifies that the tag matches package.json, resolves to the current track staging head, and can fast-forward every destination. It then uses one atomic push to synchronize the track's development branch, trunk (master or main), and all three release-order branches; either every ref updates or none does. dryRun=true performs all validation without pushing. dryRun=false performs the atomic synchronization and releases the candidate to those destinations.

Safe sequence: run Step 1 with dryRun=true, then Step 1 with dryRun=false; copy its release tag; optionally preview and run Step 2 for each needed release-order branch; finally run Step 3 with dryRun=true, then dryRun=false.

Recover an incomplete v3 kit publication

A real v3 Step 1 run can publish core and create the GitHub Release before all 33 kits finish. If the kit job fails:

Do not start a newer release or run Step 2 or Step 3.
Copy the exact release tag from the failed Step 1 run.
Use the failed job and npm package audit summary to identify the first missing or rejected kit. Correct its npm or trusted-publisher configuration.
Dispatch Staging Release - Step 1 from v3-staging with track=v3, dryRun=false, and resumeKitReleaseTag set to the failed run's exact tag.
Wait for recovery to verify core and all 33 kits at that version on next. Existing byte-identical packages are skipped and only missing kits publish.
Continue to Step 2 or Step 3 only after the recovery run is green.

If recovery reports that the tagged core version is missing from npm, stop the kit recovery. Semantic-release may have pushed the generated staging commit and tag before core publication failed:

Wait for npm propagation and confirm whether the tagged core version exists.
If core appears, rerun the kit recovery above with the same tag.
If core is confirmed absent, use the controlled maintainer procedure to restore v3-staging to the parent of the generated release commit and delete the automation-created orphan tag.
Rerun a normal Step 1 release with resumeKitReleaseTag empty.

Do not delete or move the tag until npm absence is confirmed. An npm publish that times out locally can still succeed in the registry.

If core's next tag changes without a corresponding Step 1 Git tag, do not use the bootstrap exception or guess a recovery tag. Stop releases and reconcile the unexpected npm and Git state before continuing.

The release controls must remain synchronized across the v2 and v3 trunks. These files must be byte-for-byte identical on master and main:

.github/workflows/staging-step-1.yml
.github/workflows/staging-step-2.yml
.github/workflows/staging-step-3.yml

Any change to any release step must be applied to both master and main before running a real release. Every dryRun=false workflow verifies all three files and rejects the release if either branch has a different version. Additionally, the current Step 1 workflow must be present on staging for v2 and v3-staging for v3 because GitHub executes the workflow definition from the branch selected in the Use workflow from dropdown.

Support

support@mparticle.com

License

The mParticle Web SDK is available under the Apache License, Version 2.0. See the LICENSE file for more info.

This project is tested with BrowserStack

Name		Name	Last commit message	Last commit date
.claude/skills		.claude/skills
.github		.github
dist		dist
scripts		scripts
src		src
test		test
.babelrc		.babelrc
.eslintrc		.eslintrc
.gitignore		.gitignore
.nvmrc		.nvmrc
.prettierignore		.prettierignore
.prettierrc		.prettierrc
.travis.yml		.travis.yml
AGENTS.md		AGENTS.md
ARCHITECTURE.md		ARCHITECTURE.md
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
jest.config.js		jest.config.js
package-lock.json		package-lock.json
package.json		package.json
release.config.js		release.config.js
rollup.config.js		rollup.config.js
rollup.test.config.js		rollup.test.config.js
snippet.js		snippet.js
snippet.min.js		snippet.min.js
snippet.rokt.js		snippet.rokt.js
snippet.rokt.min.js		snippet.rokt.min.js
tsconfig.json		tsconfig.json
tsconfig.types.json		tsconfig.types.json
tslint.json		tslint.json
yuidoc.json		yuidoc.json

Navigation Menu

Uh oh!

Repository files navigation

mParticle Web SDK

Documentation

Include and Initialize the SDK

Option 1. Load mParticle via Script Tag

Option 2. Self host mParticle via NPM

1. Add the SDK via NPM

2. Customize and Initialize the SDK

Creating an Integration

Contributing

Development Notes

Three-step release process (maintainers)

Recover an incomplete v3 kit publication

Support

License

About

Releases

Packages

Used by

Contributors

Languages

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

mParticle Web SDK

Documentation

Include and Initialize the SDK

Option 1. Load mParticle via Script Tag

Option 2. Self host mParticle via NPM

1. Add the SDK via NPM

2. Customize and Initialize the SDK

Creating an Integration

Contributing

Development Notes

Three-step release process (maintainers)

Recover an incomplete v3 kit publication

Support

License

About

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages