Customize guides with guide logic

Subscriptions that include Guides Pro allow Pendo users to implement advanced guide customization without using code blocks. Customizations include:

• Skipping ineligible guide steps.
• Conditional guide branching.
• Marking required questions.
• Guide personalization, for example, metadata substitution.

Prerequisites

To use guide logic, you must have:

• Guides Pro included in your subscription. To check that you have this or to include it in your subscription, contact your account representative.
• Web applications. Mobile applications can't use guide logic.
• The Visual Design Studio. Guide logic isn't supported in Adopt Studio. If you open a guide that has guide logic in Adopt Studio, the guide logic remains as plain text.

Skip ineligible guide steps

You can use guide logic in walkthrough guides to avoid steps that might fail to render within a guide flow. For example, if a guide includes a step that’s anchored to an element that doesn't always show based on a visitor's role or in-app configurations, you can use guide logic to skip this step.

1. Find and open your guide and then select Manage in my app to open the Visual Design Studio.
2. Open the guide step before the one that might need to be skipped.
3. From the table below, enter the appropriate syntax within the aria-label input field of the step. 

The check for eligible steps happens on the tagged Page where the step with the syntax is added. To check the eligibility on a different Page, add a step to the Page that the visitor is taken to. The syntax doesn't perform the navigation and the check is run prior to the navigating.

The following syntax doesn't work on the first step of a guide. It must appear on the step before the step that might be ineligible to show.

Syntax	Description
{skipStep: auto/}	If, through a next step or previous step action, the guide moves to a step that's ineligible, the guide progresses to the next or previous eligible step. If there are no eligible steps in a particular direction when moving from the current step, the guide closes.
{skipStep: [number]/}	If, through a next step or previous step action, the guide moves to a step that's ineligible, the guide progresses to a particular defined step, as indicated by the step number. For example, the syntax {skipStep: 7/} forces the guide to move to step 7 if the guide encounters a failed step.

A successful configuration of this syntax within a guide’s aria label shows a designated icon in the bottom-right corner of the guide step. This icon disappears when the guide is previewed or live:

Conditional guide branching

You can move the visitor from one step to another within the same guide based on their responses to a multi-select poll. There are two syntax tags required to enable conditional guide branching on a guide step. This syntax only applies to multi-select polls that use radio buttons. It doesn't support dropdown menus.

To implement conditional branching

1. Create or find and open a guide with a multi-select poll and then select Manage in my app to open the Visual Design Studio.
2. Ensure the multi-select poll includes radio buttons rather than a multi-select dropdown menu. Dropdown menus aren't supported for conditional branching.
3. Include the following syntax from:
   • Add {branching/} to the text block in the multi-choice poll that you want to implement the conditional branching for. This indicates that this particular poll must be utilized for conditional branching. A branching icon ()  is shown next to the poll question, indicating that the branching is active. This icon disappears when the guide is previewed or is live.
     
     
     
     
   • Add {goto- [number]/} to the answers for the radio buttons of the poll to specify which step to navigate the visitor to if they select it and then submit the poll. For example, the syntax, {goto-4/}, forces the guide to advance to step 4 when the poll is submitted.
     
     

Only one poll for each guide step can include a conditional guide poll. If multiple polls in a single step include the {branching/} syntax, the Visual Design Studio indicates that this isn't supported:

Mark required questions

You can mark any open-text poll, multi-choice poll, or number-scale poll as "required", prompting the visitor to complete the specified questions before they can submit the poll.

1. Create or find and open your guide and then select Manage in my app to open the Visual Design Studio.
2. Add the following syntax to any open-text poll, multi-choice poll, or number-scale poll that you want to make "required": {required/}

This adds a red star asterisk (*) next to the question and prevents the visitor from being able to select any buttons that submit and advance the guide until the required questions are completed. When the guide is rendered in preview or is live, any buttons that submit the guide poll are grayed out until all indicated questions are completed by the visitor.

Guide personalization

You can dynamically insert Pendo agent metadata values into the text of a guide: {[visitor/account].[fieldName]|[optionalFallback]/}

For example: {visitor.name|Gary/}

This supports any metadata on the visitor or account object that's present to the user at the time of guide rendering. The guide personalization syntax accepts either the visitor or account object specification, followed by any field name present on that metadata object. For example, if the account metadata object has a field called country, you can specify {account.country/} to dynamically insert that value from the metadata.

The syntax also accepts an optional fallback parameter. So, if the particular account viewing the guide in the example above doesn't have a country defined, you can enter {account.country|your country/} to render the words “your country” if the country metadata field for that account is blank.

You can also use the syntax within URLs in guides, in either guide logic syntax hyperlinks or URL link actions on buttons. This allows you to create dynamic URLs based on metadata. For more information and instructions, see Share Pendo metadata through a guide integration.

The guide personalization icon appears when personalization is active in both the Visual Design Studio and when the guide is previewed or live. Only agent metadata is supported for guide personalization. Other metadata types aren't supported. For information about metadata types, see Configure visitor and account metadata.

Localization and guide logic

All of the above syntax tags are compatible with XLIFF files and localization in Pendo. When translating a guide, leave the syntax in place, in the English language.

Required question example

• en_us: How can we improve this feature? {required/}
• es-419: ¿Cómo podemos mejorar esta característica? {required/}

Guide personalization example

• en_us: Please tell us about your experience in {account.country|your country/}
• es-419: Cuéntame sobre su experiencia en {account.country| España/}/}

Note: The optionalFallback for guide personalization doesn't need to be the same between translations.

Conditional branching example

• en_us: What is your role? {branching/}
  • Product Manager
  • Engineer {goto-3/}
  • Marketing {goto-4/}
• es-419: ¿Cuál es tu papel? {branching/}
  • Gerente de Producto
  • Ingeniero {goto-3/}
  • Mercadeo {goto-4/}

Aria label example

To translate the Aria label, open the XLIFF file for the required language and ensure that the trans-unit is updated appropriately for the language:

trans-unit id="e637cba3-d392-4274-a4ec-54a6a39b7dfa|ariaLabel"><source><![CDATA[{skipStep:auto/}Aria
  Label Example]]></source><target><![CDATA[{skipStep:auto/}Ejemplo
  de etiqueta Aria]]></target><note>LinearLayout</note></trans-unit&gt

Visual Design Studio example

Preview example

Guide logic with extension applications

Guide builders can use guide logic with extension applications, but can only be included in guides created with the Visual Design Studio.

Requirements

To use guide logic with your extension applications, you must have Pendo Launcher 5.26.1 installed. For more information, see the IT guide to deploying the Pendo Launcher.

Use guide logic

1. In Pendo, select your Adopt subscription.
2. In the left-side menu, go to Guides > Guides.
3. Find and open a guide that's been created in the Visual Design Studio.
4. Select Manage in my app. This opens Visual Design Studio.
5. Add guide logic as required. You can see the guide logic icons in the Visual Design Studio preview to verify that everything is applied correctly.

To use guide logic syntax in a guide previously built in Adopt Studio:

1. Find and open a guide that's been created in the Visual Design Studio.
2. Change the guide to one that was created in Adopt Studio. Select the dropdown menu arrow next to the name of the guide created with the Visual Design Studio and choose the guide that was created with Adopt Studio.