Skip to content

Latest commit

 

History

History
282 lines (202 loc) · 19.6 KB

index.md

File metadata and controls

282 lines (202 loc) · 19.6 KB
Raw
title order
Getting Started
1
5/4/2022 - Note that all mParticle workspaces will be migrated to our batching events endpoint on 7/12/2022. If your mParticle workspace was created before 5/6/2021 and you haven't already reached out to your customer support manager to enable event batching on your account, your account will automatically be migrated. See more info about event batching below.

mParticle's web SDK is designed to flexibly support all modern browsers as well as connected TVs and other Javascript-based client-side environments.

Create an Input

To send data from your web app to your mParticle workspace input, navigate to Setup > Inputs and select the Web platform. The web SDK only needs the API Key (not the API secret), which you'll replace in the snippet below. Reference the guide section for information on creating inputs.

Add the SDK Snippet

You have 2 options for implementing the Web SDK, via snippet, or self hosting. 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(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>

Verify connection

As soon as you load a page with this snippet, you should be able to see data arriving in your live stream:

If you don't see data in the live stream after loading the page:

  • Verify that the API key in your snippet correctly matches your workspace's web input
  • Verify that the window.mParticle.config object contains isDevelopmentMode: true
  • Use your browser's developer tools window to verify that web requests to all *.mparticle.com domains are succeeding

Listen for SDK Initialization

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:

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
  }
);

Upload Interval / Batching

To confirm if your workspace has event batching enabled:
What do you need to do to prepare for event batching if I am not currently on event batching?
  • If you load the mParticle SDK via our CDN, you don’t have to do anything at all. The update is simply a database change on our side, which is sent to the SDK when loaded.
    • <li>If you self host, you need to be on a minimum of version 2.9.12 (released 10/12/2019) to take advantage of batching.  We always recommend updating to our latest versions to ensure you have all bug fixes and features.</li>

All new workspaces created on or after 5/6/2021 will be enabled for event batching on web. To save bandwidth and improve site performance, mParticle will assemble events into batches and each batch will be uploaded every 5 seconds or based on specific triggers. When a trigger is fired, the SDK will:

  • Query for the current events stored in memory
  • Assemble batches of events, enriching the batch with user, device, and other application state information
  • Attempt to upload each batch by order of creation
  • Continuously retry failed uploads whenever there is another trigger.

Batches are individually deleted from the device only upon successful upload. Additional benefits of batching include:

  • Support for User Identity Change events
  • Support for User Attribute Change events
  • Event batches are fired upon user closing a browser window

There are several events that trigger SDK batch creation and upload:

  • Every 5 seconds
  • A commerce event is recorded
  • mParticle.upload() is manually invoked
  • A user closes the window or closes/switches to another tab

mParticle uses a modern web API, sendBeacon (see MDN's documentation for more) to upload batches. If a user closes the window or closes/switches tabs, sendBeacon is responsible for still sending a the batchesto mParticle's servers. To ensure maximum browser compatibility and to capture every event, if sendBeacon is not available, the SDK will use window.fetch or XHR. XHR is used if window.fetch is unavailable. For window.fetch and XHR requests, events are sent to our servers as they are recorded.

SDK Configuration

The web SDK evaluates the window.mParticle.config object for configuration upon initialization. The complete list of configuration options is as follows and several detailed examples are below.

Setting Type Default Description
isDevelopmentMode Boolean false Development mode - All data sent through mParticle is marked as development or production. Set this to true in your test and QA environments
identifyRequest Object See description IDSync Request - a request object containing the desired initial IDSync identify request. If excluded, the SDK will use the identities of the most recent/previous user if present.
identityCallback Function object null IDSync callback - a callback function to run on completion of the initial identify request
dataPlan.planId String null The data plan ID the mParticle Events API should use to validate your data. See Data Planning for more information.
dataPlan.planVersion Number null The data plan version the mParticle Events API should use to validate your data. If ommitted, the lastest version that matches your environment will be used. See the Data Planning for more information.
appVersion String null Web app version - a version string to associate with your web app and include in all uploads
appName String null Web app name - an app name to associate with your web app and include in all uploads
deviceId String null The SDK automatically initializes a device ID (also known as a device application stamp or das). If this setting is configured, the SDK uses the passed-in device ID instead. See more info on device IDs here.
logLevel String warning Sets the amount of logging in the console. verbose provides warnings, errors, and information. warning provides warnings and errors, and none disables all logging. See Custom-Logger to customize further.
sessionTimeout Number 30 Session timeout - an inactivity timeout in minutes after which a session will expire
useCookieStorage Boolean false Flag to set the persistence storage to cookies. Defaults to false (the SDK will use local storage).
maxCookieSize Number 3000 The number of characters in the cookie string to limit the size of the mParticle cookie. When a cookie extends beyond this, the SDK will remove older users and retain the most recent users. Depending on your usage of UI, UA, this number could vary widely.
cookieDomain String See description When useCookieStorage is enabled, sets the cookie domain to use (ex: foo.example.com). Defaults to the root first-party domain where the mParticle web SDK is executing (ex: .example.com).
customFlags Object null Custom flags - several integrations require custom flags on initialization.
workspaceToken String See description The workspace token is used to scope persistent storage in cases where multiple instances of the mParticle SDK are present on the same domain. The mParticle SDK snippet will provide the value for your workspace based on the provided web API key.
requiredWebviewBridgeName String See description The name of the iOS/Android Webview bridge. Since Webview bridge version 2, this field has been required. Defaults to the workspaceToken. You must include this setting if you are working in Webview Only mode.
minWebviewBridgeVersion Number 2 The minimum version of the iOS/Android Webview bridge to allow.
useNativeSdk Boolean false Deprecated - this only applies to version 1 of the Webview bridge API. Flag to allow the web SDK to bind to a native iOS or Android webview, in an app containing the mParticle iOS/Android SDKs.
isIOS Boolean false Deprecated - this only applies to version 1 of the Webview bridge API. Flag to allow the web SDK to send data to the iOS native app. More info at Native Webviews

Identify Request

The web SDK does the following on every page load:

  • Detects if there is an active session in the current or any other browser tab
  • If an active session is not found, the SDK constructs an IDSync request containing the most recent user identities from the previous browser session. You can manually specify the IDSync request via the identifyRequest property of your mParticle.config object.
  • If an active session is found, then no IDSync HTTP request is performed
  • Regardless of whether an IDSync HTTP request is performed, the SDK will invoke the IDSync callback function described below.

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.

Environment

All data sent into an mParticle input must be marked as either "development" or "production". Whereas several mParticle SDKs attempt to auto-detect the environment, the web SDK always defaults to production.

You can override the environment in your mParticle.config object:

window.mParticle = {
  config: {
    isDevelopmentMode: true //switch to false (or remove) for production
  }
};

Self-hosting

Although including mParticle via the snippet as documented above is recommended for most implementations, self-hosting is also supported. See the Self-Hosting section for more information.

Device Id (Device Application Stamp)

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:

  1. During initialization - set window.mParticle.config.deviceId.
  2. Mid session - call 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).

Determining Which Partner SDK Version is Being Used By a Kit

The types of questions most users have about kits are:

  • What version of the partner SDK do you "support"?
  • Which version of a partner's SDK does a given app/SDK version "use"?

These are two different questions. mParticle defines "support" as - if you can build an app/site with the mParticle SDK and the app compiles, it's supported.

Therefore, we do not manually test every single version of every single kit.

We only verify that they compile. If the partner breaks their SDK, or our integration with it, it's possible that we will not know it.

If a partner breaks their SDK/our integration, it typically means they've also broken anyone who is directly integrating.

Find the Kit Source Code

The vast majority of customers are on the "latest" version of our Web SDK at all times. Note that these days are numbered as we prepare to officially support "self hosting".

In the meantime, this means our releasing scheme and tagging scheme doesn't really apply here. As of 6/11/19, to determine the version of a partner's SDK for a given web kit as follows:

  1. Navigate to the mParticle Integrations Github org.
  2. Find the repository of the partner. We use a naming convention - all Web SDK kits are named mparticle-javascript-integration-<PARTNER>.

Determine the Version

CDN-based

  • Most kits will have a top-level .js file, such as "Optimizely.js"
  • All kits will implement, somewhere in their source, an "initForwarder" API. This is where our kit will pull down a partner's SDK
  • As in this example, we are pulling down the "latest" of the Optimizely SDK:
initForwarder: function(settings, testMode, userAttributes, userIdentities, processEvent, eventQueue, isInitialized) {
  ...
  var optimizelyScript = document.createElement('script');
  optimizelyScript.type = 'text/javascript';
  optimizelyScript.async = true;
  optimizelyScript.src = 'https://cdn.optimizely.com/js/' +  settings.projectId + '.js';

Bundled

Some kits are "compiled" and we will bundle the source code of the partner's SDK with our kit and distribute it over our CDN.

Bundled - NPM

In some of these cases (Braze), we will pull in their SDK over NPM, and you can tell which version that is by looking at the package.json of the kit, as in this example.

These dependencies work similarly to Cocoapods and Carthage above, you can read the full package.json version resolution docs here

Bundled - Manual

In other cases (Adobe), we will actually manually bundle the partner's SDK in our repository. We don't have a set pattern for doing this, so you'll have to manually interpret it.

  • If you locate the source of the partners SDK, the version will be in the source code
  • We will include the version that we are using in the commit message that made the change
  • See the Adobe example here

Hard Reloading Browser to Test Changes

When making changes in the mParticle UI such as adding or removing integrations (aka kits) or changing kit configurations, the configuration is cached for up to five minutes in our CDN layer, and is cached by the web browser for one hour. If you are testing configuration options, make sure to hard refresh your browser to clear the client-side cache after approximately 5 to 10 minutes to see the new changes.

In Chrome, this is done by pressing Ctrl + F5 on Windows and Cmd + Shift + R on Mac. Other browsers may use different key combinations.