Activate your guide

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 activates 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.

You configure activation settings, such as automatic, badge, target element activation, and device type 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 actions can be used to fine-tune when a guide appears. Using these actions, 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 might 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 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's details page using the Preview button next to Manage in my 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.
  
  

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 Visual Design Studio and troubleshoot your targets, actions, and any other settings that influence guide behavior to get your desired guide experience.

Restart the preview as needed and return to the Visual Design Studio to edit the guide or exit it.

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's 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 to a visitor even if they've completed or dismissed it. Settings control how often and how many times a visitor can see the guide. The visitor must still be eligible to see the guide again according to the activation criteria. 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're 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 might see the guide at the repeat interval. Guide behavior follows normal automatic guide activation behavior, and additional views are possible if a user doesn't 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 two dismissals (default):
    • Guide Dismissals include:
    • • Selecting Close
      • Selecting a button with a Dismiss action
      • Invokingpendo.onGuideDismissed()
      • Next Step action on the last, or only, step
      • Invokingpendo.onGuideAdvanced()when a guide is on the last, or only, step
      • Submit Polls and Advanced Guide action for polls when it's on the last, or only, step
  • Never. The guide isn't dismissed before it no longer redisplays

Badge

Badges let you place a small icon next to an element on your Page. When your visitors select that element, the guide is 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 must be in Target Mode to choose the element. The badge appears next to the chosen element.

If the guide is a walkthrough, the badge location is determined by the target element and location is determined by the first step of the guide. In this case, a warning message displays:

Badge icon

Select a badge icon provided by Pendo or upload one of your own. The color of the icons provided by Pendo 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, 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.

Guide behavior

• Show on badge hover or click. Displays the guide if the badge icon is hovered over or clicked.
• Show only on badge click. Doesn't display the guide when the badge is hovered over.

Badge behavior

• Always show badge. Displays the badge next to the target element no matter what the user hovers over.
• Show badge only on element hover. Only displays the badge when the mouse hovers over the targeted element.

Badge frequency

• Show every time. Shows the badge each time the user views the guide.
• Show only once. Causes the badge to disappear for a user if they've already seen the guide.

Target element

Target element activation launches a guide when a user selects 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 might 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 guide behavior for target element activation.

Device selection

You can select which device to show the guide on when activated:

• All devices
• Desktop and tablets only
• Mobile only

No activation method

If you don't select an activation method, another option is to launch the guide through the API.

The guide can also be activated through 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 can schedule a guide start date and expiration date and time in the guide's Settings 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.

When a guide reaches its expiration date and time, it stops displaying to users immediately, even if the guide still appears as Public. The guide status changes from Public to Disabled shortly after the expiration date.

Note: When you add an expiration date and time to a guide, the guide expires at the correct time, but the Pendo UI might not show that the guide is disabled until the top of the hour when data processing occurs. For example, if a guide is set to expire at 5:30pm, it expires at that time, but that might not be reflected until 6pm. 

Element Contains rule

Guides display conditionally based on the contents of the target element using an Element Contains Rule. The Element Contains rule recognizes 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, such as input, div, or span. Avoid :contains() rules. These force an exact content match to display the guide step and might prevent an Element Contains rule from working as intended.
   
   
   
3. Turn on Enable Element Contains Rule to configure the rule. This displays 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 isn't 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 didn't.
   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 doesn't 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

    

   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 doesn't pass when setting it up. It allows you to verify that your rule works as intended.

   • If the rule passes, the guide displays
   • If the rule doesn't pass, the guide doesn't display

        

   Value is a required field. The Element Contains rule can't be saved unless a value is entered.

    

5. Select Done to save the Element Contains rule. Don't forget to save changes to the guide in the action bar.
   
   

Guide persistence

Use Guide Persistence to activate your guide when a particular element appears on your page and to ensure that the guide persists even if the anchoring element disappears from view. Guide persistence can be activated on any step of your guide.

After you’ve created your guide:

1. Select a step in your guide.
2. In the Edit Container dialog, select the Location tab.
3. Turn on the Guide Persistence button.
4. Select Done to finish, and then select Save to save your guide.