Novices Performing Miracles

    @postmates/mparticle-web-sdk

    2.12.3 • Public • Published


    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: myIdentityCallback,
            dataPlan: {
               planId: 'my_plan_id',
               planVersion: 2
            }
        },
    };
    
    //load the SDK
    (
    function(t){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(t){window.mParticle.config.rq.push(t)};var e=["endSession","logError","logBaseEvent","logEvent","logForm","logLink","logPageView","setSessionAttribute","setAppName","setAppVersion","setOptOut","setPosition","startNewSession","startTrackingLocation","stopTrackingLocation"];var o=["setCurrencyCode","logCheckout"];var i=["identify","login","logout","modify"];e.forEach(function(t){window.mParticle[t]=n(t)});o.forEach(function(t){window.mParticle.eCommerce[t]=n(t,"eCommerce")});i.forEach(function(t){window.mParticle.Identity[t]=n(t,"Identity")});function n(e,o){return function(){if(o){e=o+"."+e}var t=Array.prototype.slice.call(arguments);t.unshift(e);window.mParticle.config.rq.push(t)}}var dpId,dpV,config=window.mParticle.config,env=config.isDevelopmentMode?1:0,dbUrl="?env="+env,dataPlan=window.mParticle.config.dataPlan;dataPlan&&(dpId=dataPlan.planId,dpV=dataPlan.planVersion,dpId&&(dpV&&(dpV<1||dpV>1e3)&&(dpV=null),dbUrl+="&plan_id="+dpId+(dpV?"&plan_version="+dpV:"")));var mp=document.createElement("script");mp.type="text/javascript";mp.async=true;mp.src=("https:"==document.location.protocol?"https://jssdkcdns":"http://jssdkcdn")+".mparticle.com/js/v2/"+t+"/mparticle.js" + dbUrl;var c=document.getElementsByTagName("script")[0];c.parentNode.insertBefore(mp,c)}
    )("REPLACE WITH API KEY");
    </script>

    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:

    Running the Tests

    Prior to running the tests please install all dev dependencies via an npm install, and build the mParticle.js file as well as the test file by running npm run build:

    $ npm install
    $ npm run build
    $ npm run testKarma

    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.

    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.

    Install

    npm i @postmates/mparticle-web-sdk

    DownloadsWeekly Downloads

    0

    Version

    2.12.3

    License

    Apache-2.0

    Unpacked Size

    1.51 MB

    Total Files

    37

    Last publish

    Collaborators

    • mager
    • postmates-frontend
    • apapirovski
    • mnowik
    • postmates-fleet
    • cvanderschuere