Developers
The most common way of including mParticle’s JavaScript code on your webpage is by embedding our snippet in the <head> tag of your page. This snippet automatically fetches the necessary code for the core mParticle web SDK, plus the necessary client-side code for any enabled integrations, from mParticle’s CDN.
For most clients, including the snippet on their page, as detailed in the Getting Started section, will be the best way to instrument their web properties.
However, from version 2.9.5 of the Web SDK, mParticle gives you the ability to self-host the SDK, by installing it to your JavaScript project via NPM.
There are two key reasons why you might want to self-host:
In your project folder, install the main package, plus client-side code for any integrations you want to include, from the command line.
npm i @mparticle/web-sdk
npm i @mparticle/web-mixpanel-kitpackage.jsonBy default, mParticle packages will be added to your package.json with a caret version statement such as "^2.9.5-rc.3". This allows you to automatically upgrade to a new version, as long as the left-most number isn’t incremented.
For example, if your package.json includes the following dependency: "@mparticle/web-sdk": "^2.9.5-rc.3", an npm install might install version 2.9.7, but not version 3.0. If you wish, you can edit your dependency to an exact version.
Config options are the same as described in the Getting Started guide.
mParticleConfig = {
isDevelopmentMode: true,
identifyRequest: {
userIdentities: { email: 'h.jekyll.md@example.com', customerid: 'h.jekyll.md' }
},
identityCallback: myIdentityCallback
}When using the mParticle snippet, the SDK will automatically initialize itself on load. If you switch to self-hosting, you will need to explicitly initialize the SDK in your code.
The mParticle.init() method requires your API key, and the config object created in step 3.
mParticle.init("YOUR_API_KEY", mParticleConfig)// your main index.js file
import mParticle from '@mparticle/web-sdk';
import mixpanelKit from '@mparticle/web-mixpanel-kit'
function myIdentityCallback(result) {
console.log(result)
}
var mParticleConfig = {
isDevelopmentMode: true,
identifyRequest: {
userIdentities: { email: 'h.jekyll.md@example.com', customerid: 'h.jekyll.md' }
},
identityCallback: myIdentityCallback
};
mixpanelKit.register(mParticleConfig);
mParticle.init('apiKey', mParticleConfig)With the exception of “webhook” style integrations that accept raw JSON in mParticle’s batch format, almost all web integrations require a client-side kit. If you use the snippet, the process of fetching these client side kits is handled for you automatically when you enable an integration in the mParticle UI.
If you are self-hosting, you will need to manually add each new integration to your source code before you can successfully enable the integration. You can find a full list of kit packages by searching npm for @mparticle
In accordance with standard practice for NPM packages, the mParticle library is not minified, when installed via NPM. It is assumed that you will be minifying your app bundle as part of your deployment process.
While most of our web-kits have been developed internally and so follow a similar npm naming format (@mparticle/web-PARTNERNAME-kit), we encourage partners to develop kits as well. These partner-built kits will not have the same naming convention. Please ensure to double check the npm package names below to ensure you install the proper one:
Was this page helpful?