Guides can be presented to users using several different methods, automatic, badge, target element, and programmatic activation. A guide can have multiple activation methods to achieve the desired behavior. For example, a badge-activated tooltip can open automatically the first time the user sees it but only activate when the badge is clicked after that. If no activation options are selected, the default is programmatic activation, which means the guide can be activated from the resource center, launched by another guide, using the permalink, or with the agent API. Programmatic activation options are still available if other activation options are selected.
Automatic, badge, target element activation, and device type are configured in Activation Settings in the action bar. Element Contains rules are set up in Location settings in the first guide step.
Requirements for a guide to appear
Guides have several triggers that control when and if they display. Combinations of these triggers are used to fine-tune when a guide appears. If you understand these triggers, you can consistently show guides to narrow targeted segments in unique circumstances accurately and reliably. If your guide isn't displaying as you expect, troubleshoot these settings first.
- Status - Guide must be set to "Public" to display. "Staged" deploys the guide in your staging environment only.
- Segment - Current visitor must be included in the target segment. This can be problematic if you're testing and not in the target segment.
- Page location - Current URL must match the tagged page rule. Sitewide deploys the guide anywhere the Pendo agent is running.
- Target element for step 1 - Target element on step 1 of the guide must be visible in the UI. Elements that aren't visible unless the user takes an action can be used to control when the guide appears conditionally. The guide appears as soon as the element becomes visible.
- Target element for activation - Target element activation settings can use a different element than step 1. This element must be visible on the page and interacted with.
- Device type - The device identified by the Pendo agent must match the device type category selected in the Activation settings; all devices, desktop and tablets only, or mobile only.
- Throttling - Throttling and ordering may prioritize other published guides and limit how frequently automatic guides appear.
- Localization - Localization settings can prevent a guide from displaying if it isn't translated into the current visitor's language.
- Code blocks - Code blocks allow any custom code to be added to a guide. Some custom code can limit when a guide appears intentionally to control guide display beyond what it is available in guide settings. Bugs in code blocks, like Javascript syntax errors, can prevent a guide from rendering completely.
Guide preview
Guide preview is used to test guide behavior without publishing. Guide preview ignores status, segment, throttling, and localization settings to display the guide immediately in a preview window in the Visual Design Studio.
Launch Guide preview
Launch Guide Preview from the Guide Details page with the Preview button next to Manage in App.
Launch the guide preview in the Visual Design Studio while editing a guide using the Preview button in the action bar. You can launch the preview in the same browser or a new tab. You're returned to guide editing in the Visual Design Studio after previewing your guide after using either option.
Use Guide preview
The action bar in Guide Preview shows the activation criteria for the guide, including activation settings and targets. If the target element is visible, the target element rule is green. If it is not visible, it's red. If you're currently on the target page, the page target is green. If you're not on the target page, it's red.
Navigate in your app until the target element and target page rules are green, and activate your guide as expected. Use your app and navigate through guide steps to preview each step in a multi-step guide. If your guide isn't functioning as expected, return to the designer and troubleshoot your targets, actions, and any other settings that influence guide behavior to get your desired guide experience.
Restart the preview as needed. Return to the designer to edit the guide or exit the Visual Design Studio.
Automatic
Automatic activation displays the guide as soon as all the conditions for displaying that guide are met. All requirements for activation must be fulfilled for the guide to display.
An automatic guide displays until it is dismissed by the user, either via the ‘X’ close button in the upper-right corner or a button with the Dismiss action in the guide, or the Esc key when using keyboard navigation. Expect your users to see a guide set to automatic activation multiple times until they dismiss it. Automatic guides can be reactivated automatically after they are dismissed using repeat guide display.
If activation is set to automatic with another activation method, automatic activation takes priority. The guide is still available using other activations if frequency settings for the other activations allow the guide to be viewed more than once.
Repeat Guide Display
Repeat guide display shows a guide that a visitor has completed or dismissed again. Settings control how often and how many times a visitor may see the guide. The visitor must still be eligible to see the guide according to the activation criteria to see it again. The guide still adheres to snooze, throttling, and scheduled expiration behavior as expected.
Repeat guide display is configured in the Visual Design Studio in Activation Settings when a guide is set to activate automatically.
- Repeat every - Set how often the visitor sees the guide. The repeat interval starts when the visitor sees the guide. They are eligible to see the guide again when it has elapsed. Intervals can be set at a range of 1 - 10,000 hours or days.
- Expiration Type - Limit how many total times a visitor sees the guide or set it to never expire. The number of dismissals controls the maximum number of times the visitor may see the guide at the repeat interval. Guide behavior follows normal automatic guide activation behavior, and additional views are possible if a user does not interact with a guide. If a guide is active, it continues to display until the visitor completes or dismisses it. A repeating guide that never expires shows again on the repeat interval until the guide is disabled or the visitor is no longer in the target segment.
-
A set number of dismissals (default option) - the number of guide dismissals that are allowed before the guide no longer redisplays. Minimum is 2 dismissals (default):
- Guide Dismissals include:
-
- Clicking Close
- Clicking a button with a Dismiss action
- Invoking
pendo.onGuideDismissed() - Next Step action on the last, or only, step
- Invoking
pendo.onGuideAdvanced()when a guide is on the last, or only, step - Submit Polls and Advanced Guide action for polls when it is on the last, or only, step
- Never - the guide is not dismissed before it no longer redisplays
-
Tip: Use repeat guide display carefully and sparingly. Visitors can get guide fatigue if they receive a constant stream of guides while using your product. Repeating in-app messaging can contribute to this. It may be tempting to show a guide again until a user takes action, but it should only be done when absolutely necessary. If visitors aren't taking action after seeing a guide reconsider your guide design, messaging, or friction in your app before spamming them with the same message repeatedly.
Using a combination of activation and targeting settings can help show the guide when appropriate and remove the visitor from the segment when it's no longer relevant. For example, repeat a guide until a user updates a critical setting, but add a rule in the segment that only shows the guide to visitors who have never used that feature and target the element in Location settings on step 1, so the guide only shows when that element is visible.
Badge
Badges let you place a small icon next to an element on your page. When your visitors click that element, the guide will be shown. This is a fantastic way to add inline support to your web application - your users can request information when they need it.
Badge Target Element
When you choose the badge option, you will be in "Target Mode" to choose the element. The badge will appear next to the chosen element.
If the guide is a walkthrough, the badge location is determined by the target element and location determined by the first step of the guide so that you will see this warning message:
Badge Icon
Choose from one of our provided badge icons or upload one of your own. The color of our provided icons can be modified with the color input below the icon dropdown.
Badge Position
This determines where the badge appears in relation to the target element. Choose Top-right, Top-left, or inline.
Badge Offset
The Top and Right offset allow you to adjust the positioning of the badge in relation to the target element. Both positive and negative pixel values are accepted.
Badge Guide Behavior
"Show on badge hover or click" will display the Guide if the badge icon is hovered over or clicked. "Show only on badge click" will not display the Guide when the badge is hovered over.
Badge Behavior
"Always show badge" will display the badge next to the target element no matter what the user hovers over. "Show badge only on element hover" will only display the badge when the mouse hovers over the targeted element.
Badge Frequency
"Always show" will leave the badge in place even if a user has seen the guide before, allowing them to reference the information repeatedly. "Show only once" will cause the badge to disappear for a user if they have already seen the guide.
Target Element
Target element activation launches a guide when a user clicks on a certain element in your application. This functions similarly to badge activation but uses an element in your app instead of a badge created by Pendo.
Location
The page location is inherited from step 1 of the guide. You must change the page location on step 1 to change the page location of the target element.
The target element can be inherited from step 1 or set to a different element. You may want to activate the guide but target the step 1 guide content to a different element. For example, launch the guide when a button is clicked but target a tooltip to an input field.
Behavior
The Behavior tab controls the
Device Selection
You can select which device to show the guide on when activated.
No Activation Method
If you don't select an activation method, another option is to launch the guide via the API.
The guide can also be activated via the Guide permalink or if it’s added to the Resource Center.
Scheduling
Regardless of the activation method, if you want a guide to display for a specific period of time, you have the option of adding a "Guide Start Date" and "Guide Expires" date and time from the Guide Details Page.
If you select a start date for a guide, the guide status must be set to Scheduled for the guide to publish on the selected date.
Element contains rule
Guides display conditionally based on the contents of the target element using an Element Contains rule. Element Contains rules recognize text or numbers and can only be set on the first step of a Guide. Only one Element Contains rule can be configured per Guide.
Set up an Element Contains Rule
1. Target the element containing the value you want to validate on the Location tab of Step 1.
2. Use selectors that contain dynamic or user-entered content, elements like input, div, or span. Avoid :contains() rules. These force an exact content match to display the Guide Step and may prevent an Element Contains rule from working as intended.
3. Toggle Enable Element Contains Rule to configure the rule. This will display the current content contained in your target element. Adjust the target element if needed.
4. Select Content Type, matching option, and value. This can be text or a number with different matching options for each.
Text is not case-sensitive. Rules include punctuation and symbols. Text can be used to read input fields on user-entered text in a form. For example, the rule Does Not Contain "@" on an email field could validate if the user entered a valid email address and present a Guide if they did not.
Validation Options treat the element contents as a string and look for matches within the collected value.
- Contains
- Does Not Contain
- Exactly Matches
- Does Not Match
Number recognizes the value as a float and does not recognize certain formats such as date, time, currency, or punctuation other than decimals. For comparing values, one period following a number and a leading minus sign indicating a negative number are recognized. Commas are ignored. Any other leading punctuation is ignored. Punctuation or symbols after a number are treated as the end of the number.
- Equals
- Not Equal To
- Is Greater Than
- Is Less Than
Supported Formats
| Element Contents | Value Used for Comparison |
| 1234 | 1234 |
| -1234 | -1234 |
| 12.34 | 12.34 |
| 0.1234 | 0.1234 |
| No value | |
| $1234 | 1234 |
| 12.34% | 12.34 |
| 1,234 | 1234 |
| 001234 | 1234 |
Unsupported Formats
| Element Contents | Value Used for Comparison |
| .1234 - No leading 0 for decimal | 1234 |
| 12/34 - Fraction | 12 |
| 12:34AM - Time | 12 |
| 12/12/21 - Date | 12 |
| 1.2.3.4 - IP Address | 1.2 |
| €12,34 - Comma used in international currency | 1234 |
| (123)456-7890 - Phone Number | 123 |
| 12, 34, 56 - Space-separated | 12 |
5. The Rule builder validates the current content of the target element with the current rule. Remember the current content should be a dynamic value. It's ok if the rule does not pass when setting it up. It allows you to verify that your rule works as intended.
- If the rule passes the Guide will display
- If it does not pass, the Guide will not display
6. Value is a required field. The Element Contains rule cannot be saved unless a value is entered.
7. Click Done to save the Element Contains rule. Don't forget to save changes to the Guide in the Action Bar.