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.
Fully detailed documentation and other information about mParticle web SDK can be found at our doc site here
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.
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',
});In your root project directory, add the SDK to your package.json:
npm install @mparticle/web-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',
});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:
- Amplitude
- Appboy
- BingAds
- Device Match
- Google Analytics
- Inspectlet
- Intercom
- Kahuna
- Kissmetrics
- Localytics
- Mixpanel
- Optimizely
- SimpleReach
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.
This package comes with the NPM package pre-commit, which will run ESLint when you try to commit.
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): selectstagingfortrack=v2, orv3-stagingfortrack=v3. This workflow builds and tests the track, creates and merges a generated release branch, runs semantic-release, and publishes the npm release.dryRun=truepreviews the merge and semantic-release result without creating a branch or publishing;dryRun=falsecreates/pushes the release branch and publishes. - Staging Release - Step 2: Publish SDK Release to Release Order Branch
(
staging-step-2.yml, optional): selectmasterfor v2 ormainfor v3. The source-ref guard accepts eithermasterormain, but use the track's matching trunk. ForreleaseTag, enter the exact Git tag created by the successful Step 1 run (for example,v2.80.0orv3.0.1). Chooserelease-order-a,-b, or-casreleaseOrderBranch. For v3, that logical choice maps to the correspondingv3-release-order-*branch.dryRun=truevalidates the exact candidate and fast-forward without pushing;dryRun=falsepromotes it. - Staging Release - Step 3: Release to CDN and Synchronize Branches
(
staging-step-3.yml): selectmasterfor v2 ormainfor v3 (the source-ref guard accepts either). ForreleaseTag, enter the same exact Git tag created by the successful Step 1 run. The workflow verifies that the tag matchespackage.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 (masterormain), and all three release-order branches; either every ref updates or none does.dryRun=trueperforms all validation without pushing.dryRun=falseperforms 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.
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.
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