This article explains the functionality of Feature tagging, helps determine the quality of an automatic selection, and provides some information on how to test custom selectors.
This article assumes some technical knowledge and isn't a suggested approach for all users. If you have questions about the contents of this article or are unsure about how to continue, contact Pendo Technical Support.
Prerequisites: CSS Selectors and Chrome DevTools
Pendo’s Feature selection uses a subset of CSS selectors to identify the components of your application. We recommend familiarizing yourself both with general CSS selector knowledge as well as what we specifically permit for Pendo Features. Below are some resources to get started:
- W3 Schools CSS Selectors Reference
- Mozilla’s Introduction to CSS Selectors
- CSS Diner: A Game to Practice CSS Selectors
- What Does Pendo Support for Custom CSS for Feature Tagging?
How Feature selections work
Feature tags work by capturing user activity data using CSS selectors. This is the same as selecting elements directly from a Webpage. These events are captured as hierarchical representations of each page element that an event is logged against. Because of the way we collect and store activity, this limits the selectors we can use. Each of these selectors is referred to as a Feature rule.
How Feature rules work
Each rule for a Feature processes against the total data we’ve received and surfaces each event that the rule applies to.
A general selector (such as "any Submit button") returns a greater set of results than a specific selector (such as "the Submit button on an exact modal").
Pendo collects data in the form of hierarchical representations of page elements. This means that the level of specificity of your Feature rules can impact the total count that surfaces in the Pendo application. You can read more about this in the Determining the quality of a Feature rule section, in this article.
You can also leverage multiple rules to make selection combinations. Multiple Feature rules don't show duplicate results. Because each rule is processed within the context of a single Pendo Feature, the total count skips events that are already included by another rule. Determining how many rules are needed to accurately capture activity against a particular Feature is dependent on the implementation of your application and the goal you have for the Feature you’re tagging.
Determine the quality of a Feature rule
Depending on the implementation of your application or how a user selects a Feature when tagging, an automatic Feature rule could be selected that doesn’t ideally capture the data the way you intended. A simple and common example is a
span contained in a button or anchor tag:
In the above example, there's an anchor element (indicated by
<a...) who’s child is a
span (indicated by
</span>) that contains the text ‘Generic Page’. The highlighting in the image reveals how Feature clicks will be tracked at its lowest level: a click in the blue space will be tracked against the
span while a click in the green space will be tracked against the
anchor. If we tag this element in-app, depending on where we select, we’ll get one of two selectors:
The anchor, Rule A:
The span, Rule B:
To determine which selector is the better choice, keep in mind that we track from the most specific element of our click and up. Here is a diagram to show the core difference between the two:
Looking at Rule A (against the anchor), we can see two Click Events against it: Click 1 and Click 2. For this rule, both of these Click Events will be captured by our rule. This is because a click against the span will track from this element and up. Any rule that targets our anchor tag should capture every click of anything within it.
Looking at Rule B (against the span), we can see another two Click Events: Click 3 and Click 4. For this rule, only Click 4 is captured. This is because the click against the anchor will only collect the anchor and what is above it while our rule is pointing very specifically to the element below it.
Our best tagging selection for this element would be against the anchor, Rule A.
Test a Feature rule
Sizzle library for reading and selecting elements from a webpage. While Sizzle can be great for testing, it will cover more selectors than we allow for Features. Sizzle can't detect elements within iFrames unless querying the console at that iFrame level. For more information, see our article on supported Feature CSS selectors: Using CSS selectors in Feature tagging.
To test your rule, navigate directly to the page (outside of the designer) where your Feature lives and open the Chrome DevTools. Enter the following into the console:
There will be a dropdown with your results from your selector after you run the command:
Hovering over any of these results highlights the item inside your application:
You can also double-click the result to reveal the element in the Elements pane. Using this information in combination with the highlighting provides insight into how effective your rule is.
Dynamically rendered frameworks
Dynamically generated attributes such as classes and IDs are common in frameworks, such as React.js, EXT.js, or Ember. Pendo has created some automatic exclusions so that our Suggested Match avoids these. However, you might find that you need to customize to capture all data or to get a tooltip to show every time.
Below are some examples of dynamically generated attributes:
The numbers, here, are randomly generated on each page load, so ensure that you choose something different or wildcard (*) the match. Use
:contains when you want to capture something more specific in the query string than what we would normally gather from using a wildcard (*). You can only use the
:contains rule on the leaf-most (last) node. For example, the following won't work because
:contains isn't a part of the last rule in the set:
For more information, see Using CSS selectors in Feature tagging.
After you've used the in-app designer to tag a Feature, choose Custom CSS under Feature Element Matching.
As an example: perhaps your suggested match was `.nav_bar__2RnO8`. Pendo supports `^`, which means “the attribute begins with”. This is a great option for tagging with React.js classes. The format for `.nav_bar__2RnO8` would be:
Tip: You should see a red box around the element to indicate that you've used the right syntax to select the appropriate element.
“class” in the above example is the attribute because of the `.`, whereas this same syntax works for other attributes such as id (depicted as `#`) or `href`.
Rules Pendo supports
[attribute^=“what it begins with”]
[attribute$=“what it ends with”]
[attribute*=“what it contains”]
Note: You might want to ask your developers if you're using a custom attribute that would be a better match. Pendo doesn't capture custom attributes by default, but you can add them in the settings, which makes the Suggested Match more accurate and requires less customization. For more information, see our article on Custom Attributes.
For more guidance on CSS selectors, see the following videos on Pendo Academy: