Developers
There are two options for initializing the Web SDK:
The quickest way to get set up is by using the snippet below, but the benefits of self hosting may align with your company’s use case and policies better. Using our snippet means that you always get the latest version of the mParticle SDK and every Web Kit as we push new code.
The following snippet should be included on every page of your web app. Ideally, it should be placed within the <head> tag or otherwise be loaded as soon as possible on each page. The mParticle web SDK is lightweight (under 30KB depending on your configuration) and distributed globally via a CDN.
<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};window.mParticle.eCommerce={Cart:{}};window.mParticle.Identity={};window.mParticle.config=window.mParticle.config||{};window.mParticle.config.rq=[];window.mParticle.config.snippetVersion=2.3;window.mParticle.ready=function(e){window.mParticle.config.rq.push(e)};var i=["endSession","logError","logBaseEvent","logEvent","logForm","logLink","logPageView","setSessionAttribute","setAppName","setAppVersion","setOptOut","setPosition","startNewSession","startTrackingLocation","stopTrackingLocation"];var n=["setCurrencyCode","logCheckout"];var t=["identify","login","logout","modify"];i.forEach(function(e){window.mParticle[e]=o(e)});n.forEach(function(e){window.mParticle.eCommerce[e]=o(e,"eCommerce")});t.forEach(function(e){window.mParticle.Identity[e]=o(e,"Identity")});function o(i,n){return function(){if(n){i=n+"."+i}var e=Array.prototype.slice.call(arguments);e.unshift(i);window.mParticle.config.rq.push(e)}}var r,c,a=window.mParticle.config,s=a.isDevelopmentMode?1:0,l="?env="+s,w=window.mParticle.config.dataPlan;if(w){r=w.planId;c=w.planVersion;if(r){if(c&&(c<1||c>1e3)){c=null}l+="&plan_id="+r+(c?"&plan_version="+c:"")}}var d=window.mParticle.config.versions;if(d){var m=[];Object.keys(d).forEach(function(e){m.push(e+"="+d[e])})}var f=document.createElement("script");f.type="text/javascript";f.async=true;f.src=("https:"==document.location.protocol?"https://jssdkcdns":"http://jssdkcdn")+".mparticle.com/js/v2/"+e+"/mparticle.js"+l+"&"+m.join("&");var p=document.getElementsByTagName("script")[0];p.parentNode.insertBefore(f,p)}
)("REPLACE WITH API KEY");
</script>The web SDK loads asynchronously and is therefore not immediately available for use. However, this snippet creates stubbed versions of several mParticle APIs such that your function invocations are queued until the SDK loads. The following APIs are stubbed for you and will be placed on a function queue when invoked after the snippet but prior to when the SDK loads:
logEvent()logPageView()You may also add any function to a generic queue via the mParticle.ready() helper method and it will be invoked once the SDK loads:
window.mParticle.ready(
function() {
console.log('mParticle has loaded!');
// !! Note: do not attempt to access the user object at this point
// !! var user = window.mParticle.Identity.getCurrentUser();
// !! Instead, access the user object via the mParticle.config.identityCallback option
}
);The web SDK does the following on every page load:
identifyRequest property of your mParticle.config object. A common use-case is to access the mParticle user object immediately on page load. The best way to do this is to specify a function as the identityCallback property of your mParticle.config object:
window.mParticle = {
config: {
identifyRequest: {
userIdentities: {
email: 'email@example.com',
customerid: '123456'
}
},
identityCallback: function(result) {
//This is the quickest way to acquire a reference to the user object
//this callback is invoked on every page load
if (result.getUser()) {
result.getUser().setUserAttribute('foo', 'bar');
}
}
}
};See the IDSync documentation for more information on building a complete IDSync request.
When the Web SDK initializes, mParticle generates a random UUIDv4-formatted string to be the browser’s device id (Device Application Stamp, or das). mParticle allows developers to retrieve this by calling mParticle.getDeviceId().
The device ID is unique to each browser’s persistence layer. This means that a new device ID is generated for each browser, so if a user uses multiple browsers, then their MPID will have multiple device IDs associated with it. Additionally, if a user clears cookies/local storage, or uses a browser’s private browsing mode (ie. incognito mode), a new instance of persistence is created, resulting in another device ID.
Furthermore, if multiple people use the same computer and browser (ie. families, public computers), then a single device ID will be associated with multiple users.
mParticle allows an advanced use case for our customers to set the device ID via two different methods:
window.mParticle.config.deviceId.mParticle.setDeviceId('UUIDv2-formatted-string').Note that an invalid device ID will result in data not reaching our servers, so we recommend doing lots of manual testing if configuring the device ID. One use case is passing the device ID between an iFrame and parent page when mParticle is on both pages. In this case, you should call getDeviceId from one level (for example the iFrame) and send that value to the other (for example the parent page).
Was this page helpful?