Typically, most guide display issues are caused by guide settings, segment behavior, or ad blockers. You can always test your guide using the guide preview, using the Debugger tool, creating a test segment, or turning off ad blockers in your browser.
If none of these methods help you understand why your guide isn't displaying, you can read through these guidelines for assistance. This article reviews troubleshooting guidelines for when a guide isn't displaying as expected.
Environment: Pendo Engage, Guides (web only)
Check your browser settings
Ad blockers are plug-in extensions that you can add to browsers to prevent advertisements, such as pop-up guides, from displaying on websites. You can turn off ad blockers in your browser to allow Pendo guides to display.
Adding CNAME can also help with ensuring that events are collected and guides are served to end-users who are subject to ad-blocking software like firewalls and more.
Review the guide configuration
Pendo must be installed on a page or iframe for a guide to display. If you verified that Pendo is installed on the page or iframe where the guide needs to display and you’re still experiencing issues, check the following guide settings:
Activation. Ensure the target elements are present on the page and have valid CSS targeting rules. Automatic guides display until they're dismissed. When there isn't an activation set, programmatic activation launches the guide from a button, the Resource Center, or through API.
Guide ordering and throttling. Ensure the guide isn’t being restricted by guide-throttling.
Location. Ensure the domain matches where the guide should be displayed. The guide location is set in the Location tab on step 1 of the guide. Common location issues include:
- Target element not visible. The element target rule is incorrect or the element isn't on the target page.
- Page location setting. Sitewide or page-specific selection is restricting visibility.
- Page target mismatch. The visitor's browser URL doesn't match the target page rule.
- Targeting in iframes. The page target doesn't match the URL of the iframe where the visitor sees the guide.
Status. Ensure the guide is either set to display in Staging, where your testing environment is, or to Public, where your live domain is. Draft and Disabled guides do not display.
Segment. Ensure the visitor meets any applied segment rules for the guide to display. Visitors can fall out of segment rules, as their data is not static. When segmenting the Resource Center, the visitor must be included in the segment for the relevant Resource Center module to view the content.
Schedule. Ensure the current date and time range matches the scheduled window of the guide.
Views. Ensure the visitor has not advanced or dismissed the guide. Once advanced or dismissed, the guide won’t display again unless your activation method is configured to allow repeat displays, such as badge and target element interactions or Repeat Guide Display for automatic activation. You can verify if a visitor has seen the guide by checking the guide metrics.
Verify your application settings
Applications created after June 2023 have the preferMutationObserver application flag enabled to make the agent responsive to changes in the document. In most cases, this will yield better performance. However, a limitation of the MutationObserver API is that it does not detect changes in elements encapsulated in Shadow DOM trees. To remedy this, we have an additional configuration setting observeShadowRoots, that's available when preferMutationObserver is enabled.
Enabling the observeShadowRoots flag or disabling preferMutaionObserver will get the guide to reshow in your application. This setting can be modified by navigating to the settings page and then selecting the following settings:
- "Prefer MutationObserver to 500ms timer, when available" checkbox for preferMutationsObserver
- "Use MutationObserver on Shadow DOM elements" checkbox for observeShadowRoots, which is only present in the UI when preferMutationObserver is enabled.
For more information about Guide display issues and segment questions, see our Segment of Eligible Visitors differs when applied to Guide article.