SEARCH
Showing results for 
Search instead for 
Do you mean 

Custom Dimensions

by Community Manager on ‎08-03-2015 01:05 PM

App Admins can define dimensions to track on each beacon. Beacon-level dimensions can be defined using one of six supported pattern-matching techniques, or value types found in the Configure Apps box, Advanced view, Dimensions tab.

SOASTA recommends defining dimensions on value types that have relatively few possible values. With that in mind, a good example is a dimension used to track free and paid users on a domain.

Custom Dimensions

Dashboard performance may decrease if a custom dimension returns more than 100 unique values. So, categorical dimensions work well because they can only return a limited number of possible values.

Identity-tracking dimensions, however, are riskier for performance because they can return millions of unique values. Displaying a list of 1 million values in a dashboard will take longer to load and analyze than a list of 100 values. Examples include: user ID, session ID, and username.

Tenants are each limited to 10 custom dimensions.

Note:  For performance reasons, this feature should be used according to best practices. Best practices will prevent data explosions that are counter-productive and could result in performance hits against your app.

Within individual dimensions, an alias map can be used to create user-friendly values for display in dashboards.

Each of the six supported value types can be either text (any value), numeric (Boomerang will convert it to an integer or, if it fails, it will not persist), or Boolean (follows JavaScript truthiness).

Note:  Boolean will do JavaScript truthiness except for in the JavaScript value source itself. mPulse's server side has been tweaked for JavaScript truthiness (e.g. if it's there, then its value is 1, and if not there, then 0).

Value Sources Used to Define Dimensions

The App Administrator can use any of the following Value Source techniques to define a dimension:

  • XPath- extracts the value of a DOM Element, located via XPath.

Note:  If you require compatibility with Internet Explorer, you can only use a limited subset of the XPath language.

  • URL- extracts a portion of the URL, using a regular expression
  • Query Parameter- extracts the value of a query string parameter
  • Cookie- extracts a portion of a cookie value, using a regular expression
  • User Agent- extracts a portion of the "User-Agent" header, using a regular expression
  • JavaScript variable- extracts the value of a JavaScript variable

No matter which type you choose, the value is extracted on the client side (inside the browser).

URL Patterns

Some custom dimensions only apply to a portion of your website. In those cases, you can limit the set of URLs for which the dimension value will be extracted, using the "URL Pattern" input. For example, if a custom dimension only applies to the online store portion of your site, the URL pattern might be http://www.mywebsite.com/store/*.

Note that URL patterns are not regular expressions. Their syntax is limited to asterisk wildcards.

URL Patterns

Dimension Types

Dimensions may be of three (user facing) types:

  • Text - Some text on a page; can be any value
  • Numeric - A count on a page such as the number of advertisements
  • Boolean - A 0 or 1 for Boolean (implemented as a Numeric)

To define a Text type Dimension by Alias Map, define some token value on the left and an English-readable string on the right. This will match a value defined in the web or mobile app. Similarly, a numeric value from a JavaScript can be aliased to have a text value.

Alias Maps

In some cases, the actual value extracted at runtime is not the value that you want to display in dashboards. For example, let’s say you’re setting up an "Account Type" dimension, whose values are "Free", "Pro", or "Enterprise". The value will be extracted from a cookie, but it turns out that the cookie uses internal codes, like "f", "p"and "e".

You can define an Alias Maps to translate the internal values collected in the browser to "user-friendly" values that will be shown in the mPulse dashboard and alert UIs.

For example, a simple Alias Map for user authentication status plus user type might be defined using the following user-defined values and aliases (with the numeric dimension type):

0 = Logged Out
1 = Logged In Lite User
2 = Logged In Pro User
3 = Logged In Elite User

Alias Maps

For the map defined above, mPulse will get the numeric value and place it on the beacon, save that value to the database, and then display the user-friendly alias in dashboards (e.g. as Logged Out, Logged In Lite User, etc.).

Defining a Dimension Using XPath

XPath matching works similarly to the matching presented in mPulse via the Metrics tab and can also be filtered by URL pattern. When this value source is selected, define an Xpath from which to match.

For example, a news site might create a custom dimension called "Market Vertical," which uses XPath to pull the type of news content that the user is currently viewing.

Defining a Dimension using XPath

  1. Enter the dimension name and (optionally) description.
  2. Select the desired data type (Text, Numeric, or Boolean).
  3. Optionally, if the dimension only applies to certain pages within your site, set the URL Pattern to match those pages.
  4. Set the Value Source drop-down to XPath.
  5. Enter the XPath of the DOM element that will contain the dimension value.
  6. Optionally, configure an Alias Map to translate the DOM element values to user-friendly names.

Note:  If you require compatibility with Internet Explorer, you can only use a limited subset of the XPath language.

Defining a Dimension Using URL

URL matching works similarly to the matching presented in mPulse via the Page Groups tab and can also be filtered by pattern.

For example, an ecommerce site might create a custom dimension called "Product Type" that uses a Regex capture group to pull the product type from a URL, and a replacement value to capture the specific product value, such as hammer.

Defining a Dimension Using URL

  1. Enter the dimension name and (optionally) description.
  2. Select the desired data type (Text, Numeric, or Boolean).
  3. If the dimension only applies to certain pages within your site, set the URL Pattern to match those pages.
  4. Set the Value Source drop-down to URL.
  5. Enter the regular expression that captures the portion of the URL you want to extract.
  6. Optionally, configure an Alias Map to translate the extracted strings to user-friendly names.

Defining a Dimension Using Query Parameter

Query Parameter matching works similarly to the matching presented in mPulse via the Page Groups tab. When this value source is selected, define a query string parameter from which to match. The URL used here must have a query string (e.g., a "?" that precedes the non-hierarchical data that follows).

For example, the Query Parameter value source can be used to pull the value of the common query parameter, referrer.

Defining a Dimension Using Query Parameter

  1. Enter the dimension name and (optionally) description.
  2. Select the desired data type (Text, Numeric, or Boolean).
  3. If the dimension only applies to certain pages within your site, set the URL Pattern to match those pages. This is strongly recommended for the Query Parameter value source, because most query parameters only apply to a subset of URLs.
  4. Set the Value Source drop-down to Query Parameter.
  5. Enter the name of the query parameter that contains the dimension value.
  6. Optionally, configure an Alias Map to translate the extracted strings to user-friendly names.

Defining a Dimension Using Cookie

Cookie matching works similarly to the matching presented in mPulse via the Page Groups tab.

For example, many e-tailers store the marketing campaign value(s) that resulted in a web site hit. Using the Cookie value source to define a custom dimension, we can extract that information from a cookie named details, and then get the campaign name using a replacement value.

Defining a Dimension Using Cookie

  1. Enter the dimension name and (optionally) description.
  2. Select the desired data type (Text, Numeric, or Boolean).
  3. If the dimension only applies to certain pages within your site, set the URL Pattern to match those pages.
  4. Set the Value Source drop-down to Cookie.
  5. Enter the cookie name.
  6. Enter the regular expression that will determine which portion of the cookie value is used.
  7. f you have Regular Expression replacement strings (e.g. from a reference) then they can be used in the Replacement field. The string entered here should be the text that will replace a regex match after a search.
  8. Optionally, configure an Alias Map to translate the extracted strings to user-friendly names.

Defining a Dimension Using User Agent

User Agent matching works similarly to the matching presented in mPulse via the Page Groups tab.

For example, a physical retailer may have specialty in-store kiosks whose user agents (e.g. browsers) are identified by a kiosk-code such as "kiosk-code:5869:". In such a case, mPulse can capture this user-agent string from their internal site's instrumentation.

Defining a Dimension Using User Agent

  1. Enter the dimension name and (optionally) description.
  2. Select the desired data type (Text, Numeric, or Boolean).
  3. If the dimension only applies to certain pages within your site, set the URL Pattern to match those pages.
  4. Set the Value Source drop-down to User Agent.
  5. If you have Regular Expression replacement strings (e.g. from a reference) then they can be used in the Replacement field. The string entered here should be the text that will replace a regex match after a search.
  6. Optionally, configure an Alias Map to translate the extracted strings to user-friendly names.

Defining a Dimension Using JavaScript Variable

JavaScript Variable matching works similarly to the matching presented in mPulse via the Page Groups tab.

This option allows you to handle more complex extraction scenarios, by writing JavaScript that captures the value and then makes it available to mPulse.

Defining a Dimension Using JavaScript Variable

  1. Enter the dimension name and (optionally) description.
  2. Select the desired data type (Text, Numeric, or Boolean).
  3. If the dimension only applies to certain pages within your site, set the URL Pattern to match those pages.
  4. Set the Value Source drop-down to JavaScript Variable.
  5. Enter the JavaScript variable name.
  6. Optionally, configure an Alias Map to translate the extracted strings to user-friendly names.
Contributors