Support for self-hosting and module bundler
Learn how the newly-available self-hosting and module bundler support provide development teams with finer-grained control over their web apps, a more idiomatic integration for today's web ecosystem, increased flexibility, and improved performance.
Core to mParticle’s mission is ensuring that our customers have the latest and greatest means to integrate their customer data. Recently, the mParticle team has released 20+ new web libraries — as well as optional “kit” integration add-ons—and introduced official support for NPM and a new hosted-configuration workflow. These releases aim to provide development teams with finer-grained control over their web apps, a more idiomatic integration for today's web ecosystem, and improved performance.
With self-hosting and module bundler support, mParticle customers have full control over which version of mParticle’s web SDK is maintained in production environments. This blog will cover three example workflows your team could put into place today to help you determine which Web SDK integration approach is right for your organization, whether that is loading through script tag, self-hosting code, or self-hosting both code and configuration.
Integration workflow 1: Loading mParticle via Script Tag
Many libraries today can be add added via a script tag - meaning that at runtime, the browser will dynamically download the given library (typically from a CDN) and expose it globally on the browser's window for use.
Under the hood of this workflow, your web apps perform the following:
- The user navigates to your site, and an initial HTML content payload is returned.
- As the browser loads your site's content, it comes across the mParticle Web SDK snippet that you would have added to your document's head or body element.
- The snippet stubs parts of the SDK to allow for easier instrumentation, and then instructs the browser to fetch the actual SDK from mParticle's CDN using your Web API key.
- mParticle builds and responds with a customized version of the Web SDK including the following components:
This is a straightforward, time-tested way to add a library and it requires minimal instrumentation and developer infrastructure. All of the required code and configuration is queried and bundled for your API key. But, there is an ever-evolving web ecosystem affording developers different ways to incorporate Javascript libraries into their web apps, and a script tag might not be the preferred way for all teams.
Integration workflow 2: Self-hosted code
As of today, mParticle's SDK also supports being bundled directly with your web app code via the most popular bundlers, such as Webpack and Browserify. Some of the benefits to this approach include:
- Deterministic page loads: Rather than relying on an HTTP request to fetch the mParticle SDK code, you're able to ship the code directly with your web app's Javascript bundle. If your page's Javascript is executing, you can be sure the mParticle SDK is available and ready for use.
- Code version control: The mParticle Web SDK has always been open source and available on Github for transparency and auditability. With self-hosting, you can now decide exactly which version of the SDK is loaded in your web app.
- SDK Debugging: The SDK delivered via our script-tag is optimized and minified. Our NPM bundle mirrors the exact, unminified SDK source available on Github. During development, you can choose to keep the SDK unminified or maintain source-maps such that you can directly debug your SDK instrumentation and understand the inner-workings of the SDK. In your production builds we recommend that you optimize and minify the SDK code along with the rest of your Javascript code.
- Performance: mParticle's CDN provides global low-latency delivery, but it does represent an additional HTTP host for your site to ping on load. By self-hosting the code, it's up to you to decide your own cache policy and you can minimize HTTP roundtrips.
Helping dev teams become more agile is core to mParticle's mission, so with this release we wanted to strike a happy medium between the developer control that self-hosting provides and fast integration on which mParticle customers have come to rely. The script-tag workflow explained above relies on dynamic SDK configuration—to match that, we exposed a new SDK configuration HTTP API specifically for self-hosting. In a self-hosted scenario, the SDK knows to reach out to this API to acquire its configuration.
Under the hood of this workflow, your web apps perform the following:
- The user navigates to your site, and an initial HTML content payload is returned.
- As the browser loads your site's content, it comes across your own Javascript bundle which it then loads, likely from your own CDN provider.
- The Javascript bundle already contains all of your code as well as mParticle's SDK code, all in one shot. The mParticle SDK's public API is immediately available for use.
- In the background, the mParticle SDK requests and applies its configuration asynchronously.
Integration workflow 3: Self-hosted code and configuration
The SDK is highly configurable based on the updates that your teams publish in the mParticle dashboard. For those looking for even more control, mParticle now supports self-hosting the SDK configuration as well as the SDK code. This configuration includes:
- Integrations to configure for both your mParticle workspace's development and production environments.
- For each of those integrations, fine-grained filtering, allowing you to control the following for each integration:
- Control over which integration should be enabled based on the state of the user's GDPR consent state.
In a self-hosted configuration workflow, you can use the mParticle dashboard UI to update all of this configuration, but then use your own code pull request, review, and approval workflow to apply it to your SDK instrumentation.
Here's an example workflow you could follow:
- Bundle the SDK and any kits in your web app via NPM.
- On a regular interval, or in an ad hoc manner, run a script to pull the latest mParticle configuration JSON locally.
- Commit the latest JSON and submit a pull request for any new integrations or changes that have been made in the mParticle dashboard, as represented by the JSON configuration.
- Import the desired configuration object directly in your web app and pass it into the new mParticle web SDK init signature:
import mParticle from '@mparticle/web-sdk';
import mParticleConfig from './mpconfig.prod.json';
import gaKit from '@mparticle/web-google-analytics-kit'
gaKit.register(mParticleConfig);
// this is required to instruct the SDK that the configuration
// does not need to be refreshed by the SDK on init.
mParticleConfig.requestConfig = false;
mParticle.init('REPLACE ME', mParticleConfig);
window.mParticle.ready(
function() {
window.performance.mark('mark_mparticle_fully_loaded');
mParticle.logEvent("Example event!");
console.log('mParticle self-hosted config has loaded!');
}
);This advanced workflow allows for complete control over your mParticle implementation and also minimizes HTTP round-trips for your site at runtime. We'll be continuing to invest in documentation and tooling around the SDK configuration, and we've built a showcase web app including a simple Node-based CLI that you can use today as a reference to sync your SDK configuration.
Try it today
Check out the Web showcase project here as well as the new self-hosting documentation. We're continuously investing across other areas of the web SDK so stay tuned here for more updates, and please reach out developers@mparticle.com for any technical feedback or questions you might have about any of these new features. If you're not an mParticle customer yet but would like to learn how the self-hosted or hosted solution can help your development team do more with more of your data, feel free to get in touch!
