The Custom Error template allows you to collect error messages present in the browsed web page in order to aggregate and analyze them inside Error Analysis.
These instructions are to be used alongside the Contentsquare Tag Configurator article, which includes details on prerequisites, and Snippet creation.
Commonly used to
- Collect any text displayed on the user’s screen. For example, a text message in a banner, a pop-up, or next to a form field based on a user action.
- Collect errors that are not visible to users. For example, if there's a line of code being executed when users try to purchase an item that’s out of stock, even though your website might have logic that prevents them from getting to the purchase page (for out of stock items).
How to use it
Once you have selected the Custom Error template, use the steps below to configure this selected template and the chosen trigger.
Step 1: Complete the input fields
- Message: a description of the error. Here, you can either put a fixed string (text) of your own choice for a fixed value (e.g. form validation error), or if you are using one of the following triggers - Element Click or Tap, Element Exists, Element Insertion, Element Becomes Visible or Mouseover - you can pass the target element's text into your event, by using the ${element.textContent} expression to the Event Name field. You can also combine fixed strings and the element’s text by using concatenation. For example, Form Validation Error: ${element.textContent}
-
Attributes (optional): here you can add specific attributes of your custom error to collect information such as the kind of error, or its language.
- Attribute values can either be manual text (a string) or you could leverage it to grab element attributes. For example, ${element.className} or ${window.utag.data.error}
Step 2: Select a Trigger
Select a trigger and define the conditions that will fire the Snippet.
Available Triggers
- Element Insertion
- Element Becomes Visible
- Element Click or Tap
- Element Exists
- Element Removal
- Mouseover
Template and Trigger guidelines
Catch-all rules
You can apply the following catch-all rules for Custom Errors template:
[class*='error'i],[class*='warning'i],[class*='alert'i],[class*='danger'i]
To capture the message contents (when no personal data is exposed):
${element.textContent}
Identify trigger element(s)
To identify which element to use as your trigger, study how the page with the error you want to capture behaves. Do/es the element/s that hold the error text exist/s when the page first loads? If so, you can use either the Element Insertion or Element Becomes Visible triggers.
If, on the other hand, it/they is/are already present on the page when it first loads but is/are hidden, you would want to use the Element Becomes Visible trigger.
Both Element Insertion and Element Becomes Visible triggers allow you to choose whether you want them to trigger on each element/instance or just once per page view. If you’re looking to trigger off of a single element (like a payment failed error) you can restrict it to fire once per page view. However, if you want to capture multiple errors (like validation errors on a form where the same CSTC snippet with the same CSS selector can be used to capture all the messages for all the fields that had an error) then you would want to have it fire multiple times per page view.
Expression: ${element.textContent}
When using ${element.textContent} be cautious to avoid selecting elements (using CSS selectors) which are too broad and include other text you are not looking to capture.
Categorizing errors with key/value pairs
In addition to collecting the text of the error message, you can assign up to 5 key/value pairs to categorize each error. Both the key and value can be up to 30 characters long. For example, type : validation.
Attribute changes and Element Exists
The Element Exists trigger does not detect attribute changes (class changes, for example).
It will only detect if an element exists on a natural page load or if it exists among the elements added via a mutation to the DOM. It means that if your error elements already exist on page load, before they become visible, and they become visible only via a class change, the Element Exists trigger will not be able to detect that, even if your selectors are specific to the newly added classes after the error has become visible.