If your Guide isn't displaying as expected in your staging or production environment, you can use the Debugger tool to troubleshoot the issue. This article walks you through how to access the Debugger tool and use it to troubleshoot problems, such as Guide display issues.
Access the Debugger
- Go to Subscription Settings > Applications > Agent Settings and select Debug in the Staging or Production environment.
System Status
The Status tab shows critical system information and provides warnings for other issues.
Expand any of the issues to see more detailed information. From there, you can open the designer, view more details, and launch a guide if there is a guide related to this issue.
Info
The Info tab consists of several sections, including Agent, Guides, Throttling, and Resource Center.
Agent
The Agent section shows a variety of data, such as subscription settings and current Visitor information, useful for both Guide troubleshooting and installation verification.
- Check the visitor and account metadata that your application is passing into Pendo for the current visitor. Ensure that the metadata values fit within the segment applied to the guide you're testing. You can also use this to find your current Visitor ID and create a segment that applies to just your Visitor ID so you can test guides in production without anyone else seeing them.
- Ensure that your guide is set to the correct environment for your current testing (production or staging environment). If the guide is in production, it also shows up in staging environments.
- Check that you have the right API key. The API Key is specific to your Pendo app. To check that you have the right one, go to Settings > Subscription Settings, open the Applications tab, and find the relevant application. This opens the App Details tab by default, where you can find your API Key.
- If the API Key does match and you have a multi-app subscription, go to the Guides page in the left-side navigation, and find your Guide in the App column to see if it's registered under the app you just verified the API key for.
- Test your Page rules.
The Current URL is the normalized URL that Pendo recognizes from the page you are on. If your guide is set to a specific page, copy the Current URL in the Debugger, go to Pages in Pendo, and select the Page your guides is set to. There should be at least one rule for that Page
Select Test Rule to the right of each Page rule. In Test URL, paste the Current URL from the debugger. If the Current URL doesn't match any of the Page Rules, then the page you are on with the debugger loaded, doesn't fit the Page you have the guide set to.
For more information about URLs and Page tagging, see URLs for Page tagging.
Guides
The Guides section shows two lists: Active Guides and Excluded Guides.
- Active Guides are all the guides available to the current visitor based on Page and segment. If the guide you're expecting to load is in this list, your current visitor fits the segment of the guide and the URL you are on matches the Page the guide is set to.
- Excluded Guides are all the guides not eligible for the current visitor. A reason for this is displayed below each one in the list, as seen below. Reasons could be that the current visitor doesn't fit in the segment, or the current URL doesn't match any step's set location for that particular guide.
If the guide is not in the Excluded Guides list and you are unsure why it isn't displaying, select the plus sign (+) next to the guide to see the guide details.
The guide details are followed by information associated with each step of the guide. Here are a few things to check in both the guide details and step sections:
- Is the Launched field set to Automatic and Has Been Seen is True?
This means the guide won't display because Automatic activation means you only see it once until it's dismissed. For more information about activation settings, see Guide Activation Options – Visual Design Studio. - Does Launched include either Badge or Dom (target element activation), but in the details under Step 1, Element says not visible in red?
This means Pendo can't find the element the guide is tagged to on the current page. If you see the element on the page, try retagging the element inside the Pendo designer or, if you're comfortable with CSS and HTML, you can find the element in the DOM and verify that it fits the CSS selector.
We also have a functionpendo.Sizzle('CSSselector')you can use in the console to find out whether the CSS selector fits any elements on the page. If it fits multiple, Pendo attaches the Guide to the first element in the DOM. - Does the guide start as expected but one of the steps doesn't appear?
Restart the guide and advance until you reach the step that comes before the step that doesn't show up. Look at the guide details in the Debugger, specifically the next step details, to see if the element or page settings match for the next guide step. These show in red if they don't match.
To check the element settings see the answer to 2 above. To check the page settings, see the troubleshooting tips for the Current URL info in the Agent tab of the Debugger above.
- If the above don't resolve your guide not displaying and your guide is set to automatic, it could be due to Throttling and Guide order.
Throttling and guide order
The Throttling tab shows you if you have throttling set up, its settings, and your guide order. These can also be seen by going to Guides > Ordering.
If throttling is enabled and your guide is set to automatic activation, then the guide won't display until after that throttling time period is fulfilled.
If you don't see the guide at the top of the guide order list and it's set to automatic activation, then the Guide won't display until the automatic guides above it in the order have been seen first.
For more information, see Guide ordering and throttling.
Resource Center
The Resource Center tab looks similar to the Guides tab. The first block is the Home View, which is the first thing you see when you open the Resource Center. Each block thereafter corresponds to a module inside of your Resource Center.
For troubleshooting Guide display issues in the Resource Center, first identify the Onboarding or Guide List module in the Resource Center tab of the debugger.
Is Has Content set to False?
This means that the module has no guides eligible for view. Check if the guide is listed under the Children header.
If the guide is in the list, and it says it's in the payload, check that the segment applied to the module applies to the visitor metadata in the Agent tab.
If the guide is in the list, and it says it isn't in the payload, go to the Agent tab to troubleshoot further.
If the guide isn't in the list, go to your Resource Center in Pendo, and check that the guide is in that module, and that it's been pushed to the appropriate environment (staging or production).
Further troubleshooting
If you're still having issues after going through this checklist, you can Get help with Pendo from Technical Support.
Disable the Debugger
Don't forget to turn off the debugger when you're done. Enter pendo.disableDebugging() in the developer tools console.