Detecting and displaying the right element
Brief overview
One of Userpilot's main use cases is giving you the power to onboard your users and improve product engagement by implementing experiences that help your end-users tour around your web app and highlights some important features.
These experiences could contain tooltips, driven actions or native tooltips that are anchored to certain elements on your web app interface thus properly detecting and selecting the right element is key.
How elements are used in Userpilot
- Highlighting certain elements on your web application interface
- Attaching a spotlight to an element on the page
- Displaying a flow step by anchoring it to an element on the page
- Continuing a flow once the element doesn't exist on the page
How to select an element in Userpilot
Once a new step has been added that requires an element to be selected, you'll notice that a highlighted rectangle follows the cursor around the screen, the Userpilot builder is picking up every CSS element that you might want to attach the step to.
After an element has been selected in our builder, we automatically choose the best positioning for the UI pattern to be displayed and create a CSS selector for the element. Once Userpilot displays a tooltip, driven action, or a native tooltip, it uses the saved info to correctly identify and display the relevant element on the page.
Since this process is unique for every web app, it is useful to know how to make manual adjustments just in case you needed to.
Manual element detection
It is important that the selected element is properly detected to prevent a spotlight or flow step from not triggering. You can be specific about the element you're attaching the step to by enabling the 'Manual Detection' option in the settings. Once enabled, you'll be given the ability to change the CSS selectors for the tagged element in Userpilot. The ideal scenario is that the element order is 1/1, which indicates that the selected element is unique.
What is a CSS selector?
Elements are simply boxes on the page identified by their HTML and CSS, Userpilot identifies the element you have selected using CSS Selectors: these are used to select and target the HTML content on your web app. There are a wide variety of CSS selectors available, allowing for fine-grained precision when selecting elements to style; CSS selectors select HTML elements according to their id, class, type, attribute, etc.
You can find the HTML content and related CSS selectors are used as a particular element by simply right-clicking and inspecting that element. We recommend asking your developers if you're missing information here.
When should I manually adjust the CSS selectors?
We recommend manually adjusting the CSS selectors only if your experience step is not appearing as expected. Some examples of these cases could be when:
- The element couldn't be properly detected on the page which happens in very rare few cases
- The unique element couldn't be found due to the presence of too many similar elements on the page
Pro tip: If your selected element might not appear and you want to continue your flow, consider enabling the option "Continue flow when the element does not exist" option, e.g: when your end-user has not made a certain selection.
How to manually adjust CSS selectors?
Once you have a more specific selector, enable the "Manual element detection" option. This option allows you to easily select and edit the individual selector to control how the element is selected.
Adjusting the element's position
After selecting the element, the optimal position for the UI pattern will be automatically chosen and you can simply change this positioning from the settings. Moreover, you can move the selected UI pattern after placing it on an element by using the 'fine-tune' feature in the settings.
Triggering based on element's visibility
The experience step will automatically display when the element is visible. If the item you are tagging is on the lower half of the page, you can choose "Try to find element" to automatically scroll to the element and display it when it's activated.
