Overview
Use this article to check why your Guide might not be displaying as expected in your staging or production environment. If you are still having issues after going through this checklist, please reach out to our support team.
This help article walks you through on how to start up our handy Debugger tool and use it to troubleshoot Guide display issues.
Loading the Debugger
1. In your browser window, right click on your web app page and click "Inspect"
2. This will open up the browser developer tools. Find the console tab and click on it to open, and type in pendo.enableDebugging()
and hit enter. To disable the debugger later you can use pendo.disableDebugging()
.
3. You should see a small red bug in the top left hand corner of your screen. Click on it to open the debugger.
4. The debugger will load as a side navigation bar in your browser and you will see 7 sections. This article will cover Agent, Guides, Throttling, and Resource Center.
Agent
The agent section shows a variety of data such as subscription settings and current visitor information, which are useful for not only guide troubleshooting, but also installation troubleshooting/verification.
1. The visitor and account metadata your application is passing into Pendo for the current visitor.
Make sure that the metadata values fit within the segment applied to the guide you are 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.
2. It will also show you whether you are in a production or staging environment.
Make sure that your guide is set to the correct environment for your current testing. Remember, if the guide is in production, it will also show up in staging environments.
3. The API Key is going to be specific to your Pendo app.
To crosscheck that it is the right one, go to subscription settings > view app details > and look under basic settings to see the API key. If it does match and you have a multi-app subscription, go to the Guides page, look at the second column called "App." Find your guide in the list and see if it is registered under the app you just verified the API key.
4. The Current URL is the normalized url that Pendo is recognizing from the current page you are on.
If your guide is set to a specific page, copy the Current URL in the debugger and go to the Pages page, and click on the Page your guide is set to. You will see at least one Rule for that page. Click on "Test Rule" to the right of each Page rule, and in the "Test Url" box, paste the Current URL from the debugger. If the Current URL does not match any of the page rules, then the page you are on with the debugger loaded, does not fit the Page you have the guide set to. Here is an article that goes into more detail about Urls and Page Tagging.
Guides
The Guides section will show 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 are expecting to load is in this list, that means 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 to the current visitor. A reason for this is displayed below each one in the list, as seen below. Reasons would be if the current visitor does not fit in the segment, or the current url does not 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 is not displaying, click on the + next to the guide in question to see the guide details:
The guide details are followed by information tied to each step of the guide. Here are a few things to check in both the guide details and step sections:
1. Is the Launched field set to Automatic and Has Been Seen is True?
This means the guide will not display because Automatic activation means you only see it once until it is dismissed. For more information about activation settings click here.
2. 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 cannot 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 of the Pendo designer, or if you are comfortable with CSS and html, you can find the element in the DOM and verify if it fits the CSS selector. We also have a function pendo.Sizzle('CSSselector')
you can utilize in the console. You can use it to see if a CSS selector fits any elements on the page. If it fits multiple, Pendo will attach the guide to the first element in the DOM.
4. Does the guide start as expected but one of the steps does not appear?
Start the guide over and go through until right 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. They will show in red if they do not 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.
5. If the above do not resolve why your guide is not displaying and your guide is set to automatic, it could be due to Throttling or Guide Order.
Throttling and Guide Order
The throttling tab will show you if you have throttling set up, its settings, and your guide order. These can also be seen by going to Guides > Ordering.
1. If throttling is enabled and your guide is set to automatic activation, then the guide will not display until after that throttling time period is fulfilled
2. If you do not see the guide at the top of the guide order list and it is set to automatic activation, then the guide will not display until the automatic Guides above it in the order have been seen first.
For more information on throttling click here.
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.
1. Has Content is set to False
This means that the module has no Guides eligible for view. First check if the guide is listed under the children header.
If the guide is in the list, and it says it is 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 is not in the payload, go up to the Agent tab to troubleshoot further.
If the guide is not in the list, go to your Resource Center in the Pendo UI, and check that the guide is in that module, and that it has been pushed to the appropriate environment (staging or production).
Further Troubleshooting
If you are still having issues after going through this checklist, please reach out to our support team.
Disable Debugger
And don't forget to turn off the debugger when you're done! You can do this by entering pendo.disableDebugging()
in the developer tools console.