Custom dimensions

Custom dimensions store additional data for the purpose of identifying or classifying a visitor, session or pageview. Custom dimension data can be demographic (such as gender or age range), product related (such as product codes or order IDs), or customer specific (such as a customer reward program number or tier).

Adding a custom dimension

On the navigation bar, go to settings > Property Settings > Custom Dimensions and click + Add Custom Dimension.
Enter a Name and an optional Description.
Select the Type of data you want to store in the custom dimension. The following types are available:
- String — Textual data
- Boolean — Yes/no or true/false data
- Number — Numerical data
- Choice — Data from a predefined list of options
  Note: in the Choice list (comma-separated values) field, enter a comma-separated list of options to chose from. For example, "Gold,Silver,Bronze".
Select the Scope for the custom dimension:
- Session — Data applies to the current session, such as the order ID of a completed transaction
- Visitor — Data applies to the current visitor across sessions, such as the visitor's reward program tier
- Page View — Data applies to the current pageview only, such as the product ID of the product displayed on the page
Select the Integration method for custom dimension data retrieval:
- Decibel JavaScript API Call — Pushes custom dimension data using an on-page call to the Decibel JavaScript API.
- Load from JavaScript Variable — For data exposed in a JavaScript variable on the page, such as in Data layers. Enter the JavaScript variable name in JavaScript variable.
- Retrieve from URL Parameter — When the value is present in a query string parameter in the page URL. Enter the URL parameter name containing the data in URL parameter. The parameter must be in the form name=value. For example, if the URL query looks like this ?productId='05282', then productId is the name.
Click Save Custom Dimension.

You can now use custom dimensions as segment filters and to search for sessions matching the custom dimension data.

Triggering custom dimensions with Decibel JavaScript API call

To use the Decibel JavaScript API Call, your web page must include JavaScript integration code to the submit the data for the property.

To view the integration code necessary for an custom dimension, in custom dimension settings, click Show integration code in the Actions column. For example, it might show code like this calling the decibelInsight() function:

<script type="text/javascript">
   decibelInsight("sendCustomDimension", "Basket Value", <<value>>);
</script>

The sendCustomDimension endpoint sends custom dimension data to DXA. The second parameter is the custom dimension name (Basket Value) and the third parameter is the value of the custom dimension to be set.

In the JavaScript for the web page, include the function call for the dimension, and include the value to submit as as the custom dimension's data. For example, this code sets a value for a custom dimension named Basket Value when a specific button on the page is clicked. in this example the data value is the label of the button:

<script type="text/javascript">
   var buttonEl = document.querySelector('#addToBasket');
   buttonEl.addEventListener('click', function () {
      var totalEl = document.querySelector('#total');
      decibelInsight('sendCustomDimension', 'Basket Value', totalEl.innerText);
   });
</script>

Using custom dimensions

You can use custom dimensions as segment filters and search for sessions matching custom dimension data, such as order IDs.

To search for sessions matching custom dimension data:

On the navigation bar, go to Analyze > Sessions > Analyze and click the Filters dropdown menu.
In the Search field, enter the item you're searching for, such as the session ID.
In the dropdown menu to the right of the Search text box, select the custom dimension name, such as Session ID.
Click Apply changes.

Sessions matching just the entered criteria appear.