mPulse Custom Metrics

Document created by DPM Admin on Jul 14, 2017Last modified by Sheril Joseph on Aug 10, 2017
Version 2Show Document
  • View in full screen mode

Metrics are user-defined values that refer to a business goal, or to Key Performance Indicators (KPIs) such as revenue, conversion, orders per minute, widgets sold, etc. In mPulse, these values are defined using the Configure App, Metrics tab.

mPulse supports the use of user-defined metrics configured using URL Pattern matching, as well as using a variable.

As of mPulse 57, the behaviour of the percentage data type has improved. Click here for information.

Note: mPulse only accepts numeric values. Boolean or text values will be rejected. For instance, conversion should return a value of 1 on the order confirmation page, and 0 on every other page. True/False will not work.

Metric Support by Browser

Because browser support varies by brand and/or version, the App Admin should be aware of the following variations.

For latest supported browsers, click here.

Browser Support (Custom Metrics):

To define metrics, use the following techniques by browser.

  • JavaScript variable—All browsers
  • URL Pattern (e.g. true/false custom metric)—All browsers
  • URL Pattern with XPath custom metric—Chrome, Firefox, Opera, Safari, iOS, Android 4+; as noted above Internet Explorer doesn't support XPath on HTML Documents

App Admins setting up metrics should also be aware of how browser variations impact setup. 

Note: Internet Explorer doesn't support using XPath on HTML Documents (e.g. Internet Explorer requires XML documents fetched via XMLHttpRequest).

 Browser Support (Timers):

For timers, use the following techniques by browser.

  • JavaScript variable—All browsers
  • Navigation Timing custom timer—Chrome, Firefox, IE 9+, Opera, Android; experimental on Safari & iOS
  • Resource Timing custom timer defined with XPath—Chrome only
  • Resource Timing custom timer defined with URL—Chrome, IE 10+
  • UserTiming custom timer—Chrome, IE 10+

Examples of defining metrics are provided below.

User-Defined Metric Settings for Web Apps

The App Admin user can configure either a variable or a URL Pattern to match metrics in this tab.

  1. Go to Central > Apps (requires App Admin privilege).
  2. Double-click on your app to open the Advanced Configuration screen, then go to the Metrics tab.
  3. Multiple (up to 10) metrics can be defined, using either Variable or URL Pattern.

 

Defining a Custom Metric using URL Pattern (Web App)

 

  1. Go to Central > Apps.
  2. Double-click on your app to open the Advanced Configuration screen, then go to the Metrics tab.

 

  1. Press Click to add a new metric.
  2. Select URL Pattern as the Value Source. Enter the URL of a page here, using * as a wildcard to replace 1 or more characters anywhere in the URL. The metric being defined will only be checked on pages that match this URL Pattern.

  1. Optionally provide an XPath to match a DOM node within the page.  
    • If an XPath is provided, the custom metric value will be the value of the text within this DOM node after stripping out all non-numeric characters (everything except 0-9, . and -).
    • If an XPath is not provided, then the custom metric's value is set to 1 if the URL Pattern matched, and 0 if not (e.g. it is a boolean match on URL)

TIP: When using XPath, the best way to get the XPath is to open developer tools in Chrome (or using Firebug), right click on a node, and choose copy XPath.

      URL Patterns are any regular URL with * used as a wildcard anywhere in the URL. For example, entering:

        *.google.com/*

          Will match:

            http://www.google.com/
            https://www.google.com/
            abcdefg://accounts.google.com/
            http://www.google.com/?q=hello

              But will not match (because / is required in the pattern):

                http://www.google.com

                  Defining a Custom Metric using Variable (Web App)

                  1. Go to Central > Apps.
                  2. Double-click on your app to open the Advanced Configuration screen, then go to the Metrics tab.
                  3. Press Click to add a new metric.

                    The Metrics form appears.

                    1. Give the new metric a name. Note that the name assigned here will appear for end-user selection in the Dashboard Edit Panel, Filters tab, Values drop-down.
                    2. Give the new metric an optional description.
                    3. In the Value Source dropdown, select JavaScript variable and then enter the name of the variable that is in use in your web page. This variable may be namespaced.
                    4. In the Color Range area, optionally, click the first Color Range box to set a starting color for the range.
                    5. Set the ending value of the Color Range as well.
                    6. Check the metric type that corresponds to your metric: Conversion or Revenue Metric.
                    7. Assign the correct Data Type to your Custom Metric from among Number, Currency, or Percentage.
                      • Number – Number is a sum. However, if it sums up 1s, then it becomes a count. On histograms, everything is divided by the number of sessions. Specify the number of decimal places (from right to left) to use (For 0, 12345; For 1, 1234.5; For 2, 123.45; and so forth. Check the Use Thousands Separator box to insert a comma, where applicable (for example, 1, 234.5).
                      • Currency – Currency will be displayed using a currency symbol (default is $). Specify the number of decimal places (from right to left) to use (For 0, $12,345; For 1, $1,234.5; For 2, $123.45; and so forth. Select a currency symbol to use, if not the dollar ($).
                      • Percentage – Percentage will be divided by 100 and then multiplied by 100. Specify the number of decimal places to include to the right of a given decimal point. (For 0, 12345%; For 1, 1234.5%; For 2, 123.45%; and so forth. Check the Use Thousands Separator box to insert a comma, where applicable (for example, 1, 234.5)

                    Metric Filtering

                    For widgets with a custom metric defined, ensure that the correct domain is selected in the Filter tab, and then choose Metric as the attribute, and the metric from the Value dropdown.

                    Example Metric using Variable

                    1. Define a Metric variable that will be used in your page. This JavaScript variable name may be name spaced.

                      For example, use SOASTA.cmet1 or SOASTA.custom_metric1. This variable must be globally readable.

                    SOASTA = {};
                    SOASTA.conv=1; // Define a custom metric for an order conversion


                    —Or—


                    If you also define page groups using a variable, then:

                    SOASTA = {};
                    SOASTA.pg="page group name here";
                    SOASTA.conv=1; // pass 1 for a conversion
                    SOASTA.items=3; // ex. for 3 line items in the order

                     

                    Metric Settings for Mobile Apps

                    Metric values for mobile apps are also defined using the Configure App, Metrics tab. It requires only a name match in the mPulse Configure Apps UI to go along with your project source code modifications to be operational. Users should note that for the changes can only be applied by re-submitting your app to the App Store. Use the following steps to ensure a match between the named value entered in your app configuration and that used in your source code for the given timer or metric.

                    For beacon API metrics, see iOS and Android.

                    Do all of the following to setup your custom metric:

                    1. Go to Central > Apps.
                    2. Double-click on your app to open the Advanced Configuration screen, then go to the Metrics tab.
                    3. Give the metric a name. This is also the metricName (same as in the API call). Note this metricName for use in your source code.
                    4. See iOS and Android  to implement it in your environment.
                    5. For value, pass in the value you wish to send.

                    Attachments

                      Outcomes