How to use mParticle Web SDK with the Vega SDK

Vega Open Beta Knowledge Base
1

Overview

This document outlines using the mParticle Web SDK with the Vega SDK.

We recently completed our MVP so that developers can start implementing mParticle in their Vega apps. We will continue to iterate, but we want to release this so that our partners can start implementing and testing their apps.

Currently, the MVP disables access to Persistence (such as local storage & cookies) and some other DOM related properties. In future versions, we will add support for Vega’s persistence layer and other Vega-specific versions of these disabled properties.

Should you encounter any issues or have specific requests, questions or feedback, please use the contact information at the end of this document. Please also understand that we are actively developing this SDK and will keep you informed of changes as we make them available.

Installation

Self Hosting mParticle: https://docs.mparticle.com/developers/sdk/web/self-hosting/

Our Vega SDK will only work via self-hosting (see docs more details about self-hosting). As the SDK is under active development, there are a few modifications to the steps in the doc.

NPM Configuration

For step 1, instead of installing the Web SDK from our NPM repository, use our GitHub repository’s mp-koala branch instead:

Instead of:

npm i @mparticle/web-sdk

Do this:

npm i https://github.com/mParticle/mparticle-web-sdk.git#mp-koala.0.1.0 --save

Note that only the core SDK is currently supported. Since many partners are still updating their apps to work on Vega’s platform, data will only be sent to mParticle, and not forwarded to partners yet. Attempting to add kits will result in errors or unexpected behavior and is not currently supported.

SDK Configuration

For Step 3, add the following to the mParticle Config object: usePersistence: false

var mParticleConfig = {
    usePersistence: false, // <-- new setting
    isDevelopmentMode: true,
    identifyRequest: {
        userIdentities: {
            email: '[h.jekyll.md@example.com](mailto:h.jekyll.md@example.com)',
            customerid: 'h.jekyll.md'
        }
    },
};

Apart from these two changes, the installation should be the same.

Example Configuration

Here is a full example of what your initialization should look like:

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

var mParticleConfig = {
    usePersistence: false, // <-- new setting
    isDevelopmentMode: true,
    identifyRequest: {
        userIdentities: {
            email: '[h.jekyll.md@example.com](mailto:h.jekyll.md@example.com)',
            customerid: 'h.jekyll.md'
        }
    },
    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);
    },
};

\mParticle.init('apiKey', mParticleConfig)

As our development of Vega continues, we will follow up with updated docs. Once this is ready, we will also provide specific installation instructions for any additional packages and configuration changes unique to Vega.

Known Limitations

As this is an MVP, the SDK has several limitations, including the current lack of persistence support. We plan to resolve known limitations with each subsequent release.

NOTE: This version of the Web SDK has only been tested with version 0.5 of the Vega SDK.

  • As stated above, only the core SDK will currently work. You will only see events in your Live Stream and not any downstream client side partners yet. Adding kits will not currently work and may result in app crashes.

  • Local Storage and Cookies are not supported by Vega. In a future version, we will introduce Vega’s persistence with instructions on how to use it. Since the persistence layer will come in a future update, some information will be lost upon app refresh (the list is not exhaustive):

    • DeviceId
    • SessionId
    • User Attributes
    • Identities

  • Device and Session IDs

    • These can be updated and changes will be reflected in batch uploads
    • However, they will not persist with app refreshes, and therefore there will be new IDs upon refresh

  • Consent State is not currently included within uploads

  • Updating User Identities and Attributes

    • User Attribute/Identity Change Events will be logged and appear in Live Stream
    • User Attributes and Identities will not appear in the batch. They will be added in a future revision.
    • However, identity requests during a user session will continue to return known MPIDs and will appear in batches when events are logged

  • Screen Size in Device Info

    • Screen size is currently not available
    • Vega utilizes React-Native specific APIs, for which we will investigate support

  • PageViews

    • Page Location and Title will not be available as they use the window object

  • Events uploaded upon app closing/hiding

  • The Web SDK listens for events bound to the DOM or Window to determine if the browser has been minified or closed. These are unique to a web browser which Vega does not support

  • As long as the app is running on a device, it should continue to send events

As we continue developing new features, we will provide new updates to set expectations and deliverables.

Upcoming Milestones

  1. Vega Persistence - This should resolve most of the known issues above
  2. Support of React-Native specific features

Support

For any support inquiries, feature requests or reporting of bugs, please reply to this thread or message me directly

-Alex Sapountzis
Software Engineer @ mParticle