This article explains the functionality of Feature tagging, helps you determine the quality of an automatic Feature rule selection, and provides some information on how to test custom selectors.
These guidelines are intended for those who have some technical knowledge and isn't a suggested approach for everyone. If you have questions about the contents of this article or are unsure about how to continue, contact Pendo Support.
Prerequisites
Pendo’s Feature selection uses a subset of CSS selectors to identify the components of your application. We recommend familiarizing yourself both with both general CSS selector knowledge and the CSS selectors we permit for use in Feature tagging.
To get started, here are some resources to help increase your knowledge on CSS selectors:
- CSS Selectors from Mozilla
- CSS Selectors Reference from W3Schools
- CSS Diner, a game to practice use of CSS selectors
- Using CSS selectors in Feature tagging
Here are some resources about how to use Google Chrome's DevTools:
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. Each selector is referred to as a Feature rule.
To view all supported selectors and syntax, see Using CSS selectors in Feature tagging.
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. For example, 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 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
You tag Features by identifying the most specific element you can select using the Visual Design Studio. However, in some cases, this might not capture the intended data.
It's important to especially be mindful of nested and repeated elements while tagging Features. Understanding how selectors work when tagging these types of elements allows you to more consistently tag the entire clickable element and all repeating instances of elements you want to tag as Pendo Features.
Nested elements
A common example of a nested element is a span contained in a <button> or <a> element. In the example code below, the text of the button is wrapped in a span, while the clickable portion of the button is the <a> element itself. When tagging in Pendo, you want to capture the entire clickable element.
<a href="/assets/pages/home.html" class="button>
<span>Home</span>
</a>
In this example, the clickable element of the button is in the entire blue area around the button (as seen in the images below). However, the text of the button is wrapped in a <span>.
When tagging with the Visual Design Studio, selecting the span element only captures clicks that happen on the span itself.
If you select the entire clickable area, we capture clicks on both the <a> and <span> elements.
Repeating elements
The Visual Design Studio identifies the most specific element possible based on your selection when targeting an element. If you want to tag all instances of an element that repeats on the page, you likely need to adjust the CSS selector.
For example, consider a table with checkboxes that allows users to select a table row. When using the designer to tag the checkbox, we identify the most specific element, which is the single checkbox selected.
In the example image below, the selected element match is span > .pendo-checkbox >
.pendo-checkbox__input > .pendo-checkbox__inner.
If you want to instead tag any of the checkboxes in the table, you must update the selector to only use the element class. This allows the capture of clicks on any checkbox in the table to be associated with this Feature. In this example, you'd use .pendo-chckbox__inner as the custom Feature rule.
Test a Feature rule
Sizzle library for reading and selecting elements from a webpage. While Sizzle can be useful for testing, it covers 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 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, then enter the following into the console, replacing _FEATURE_RULE_HERE with your Feature rule:
pendo.Sizzle('FEATURE_RULE_HERE')After you run the command, this shows a dropdown that contains the results of your selector:
Hover over any of these results to highlight 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 modify the rule to capture all data or to get a tooltip to show every time.
Below are some examples of dynamically generated attributes:
.nav_bar__2RnO8
#ember123
#btn-1050-el
The numbers in these examples are randomly generated on each page load, so it's important to 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: .rule:contains("stuff") .another-rule.
For more information, see Using CSS selectors in Feature tagging.
To modify the rule while tagging a new Feature or editing an existing Feature rule in the Visual Design Studio, find the Feature Element Matching section and select Custom CSS.
For example, if your suggested match was .nav_bar__2RnO8, you could modify your rule using ^, which means “the attribute begins with”. This is a useful option for tagging with React.js classes. To use this when modifying .nav_bar__2RnO8, you'd enter the following as the custom CSS for the Feature rule:
[class^=“nav_bar__”]
Tip: You should see a red box around the element to indicate that you've used the correct syntax to select the appropriate element.
In this example, class is the correct attribute because of the period (.) in the suggested match. This same syntax also works for other attributes, such as id (depicted as #) and 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 as the Feature rule, which makes the Suggested Match more accurate and requires less customization. For more information, see HTML attributes in data collection.
Additional resources
For more guidance on CSS selectors, see the following videos on Pendo Academy: