Create an embedded guide

This article provides instructions for creating a guide that's embedded into your application. 

If, instead of an embedded guide, you want to create a guide that appears over the top of your application, see Create an overlay guide.

Prerequisites

• A minimum Pendo agent version of 2.252.0.
• Guides Pro included in your subscription. For information, contact your Pendo account representative.
• The correct user permissions to create embedded guides. For more information, see Permissions in this article.

We also strongly recommend that you read the best practices for embedded guides before creating one for the first time. For a summary of best practices for using embedded guides, see the Guides overview.

Permissions

There are three guide roles with different permissions: Guide Creator, Guide Publisher, and Guide Content Editor. Admin users have all of the following permissions.

• Pendo users with Guide Creator role permissions can create and edit guides from scratch, and edit an existing guide that’s not public.
• Pendo users with Guide Creator or Guide Content Editor role permissions can create and edit guides from layouts and templates.
• Pendo users with Guide Publisher role permissions can publish and schedule guides.
• All guide roles can delete draft, staged, and disabled guides.

You can also create custom user roles with a combination of the following guide permissions as needed:

• Create and edit guides from scratch.
• Create and edit guides from layouts.
• Publish guides.
• Edit and delete public guides.
• Delete draft, staged, and disabled guides.

For more information, see Roles and permissions.

Process overview

Setting up an embedded guide involves the following:

1. Start creating a guide. Open the Visual Design Studio and choose your guide configuration options.
2. Edit the location of your embedded guide.
3. Add and edit content using building blocks.
4. Optionally, add steps to your guide. This allows you to create a carousel of content in the same location of your application.
5. Edit the styling of your guide steps.
6. Configure your guide activation behavior.
7. Save and preview your guide.

You can then test and configure your guide delivery:

1. Test your guide. You can do this in your staging and production environments.
2. Segment your guide to target specific visitors.
3. Publish your guide. Optionally, you can also schedule your guide.

For instructions, see Test and deliver your guide.

Step 1. Start creating a guide

To start creating an embedded guide:

1. From the left-side menu, go to Guides > Guides.
2. Select Create guide in the top-right corner of the page. If you want to create a guide using AI, select the arrow and select Create guide with AI. For more information about this functionality, see Create guides using AI.
   
   
   
   
3. If you have multiple web applications set up in your Pendo subscription, choose the application that you want the guide to display on. A guide can only be delivered on one application in your subscription.
   
   
   
   
4. Optionally, select a category for your guide. This allows you to see recommended layouts for the category. For more information, see Use guide layouts.
   
   
   
   
5. Select Embedded to create a guide that integrates into your application.
   
   
   
   
6. Select a layout from either your saved layouts or Pendo's default layouts.
   
   
   
   
7. Name your guide. Select the default title at the top of the page or enter a new guide name.
   
   
   
   
8. Use the dropdown menu below the title of the guide to add a Product Area. You can either choose an existing Product Area or create a new one by selecting + Create Product Area. For more information about Product Areas in Pendo, see Product Areas.
   
   
   
   
9. In the Content area of the Settings tab, enter the application URL, and select Launch Designer. This opens the Visual Design Studio over your application in a new tab where you can start editing your guide. . The URL you enter here doesn't control where in your application your guide displays to your visitors. Guide location is configured separately in the Location tab of the Edit Container window. For more information, see Edit location in this article.
   
   
   
   
10. Choose a location for your guide. A dotted red box encapsulates elements in your application as you move your mouse around the page. This changes to a solid red line when you select a UI element to embed your guide into. You can either keep the Suggested Match or:
    • Expand your selection to a larger element using the Parent Element option.
    • Refine your selection using the Custom CSS option. For guidance, see Using CSS rules for guide targeting.

You can't select void or canvas elements for embedded guides. HTML void elements don't have any child nodes and so can't have content embedded within them. HTML canvas elements only contain graphics, and so content can't be embedded within them. For these reasons, you can't embed guides in the following elements: a, area, audio, base, br, canvas, col, embed, hr, img, input, link, meta, meter, param, progress, source, svg, track, video, or wbr.

For optimal results, we recommend collaborating with your engineering team to create a div or container with a unique ID to serve as the embed location. For more information, see Guides overview.

Step 2. Edit location

Embedded guide location and position are edited in the Location tab of the Edit Container window. If the Edit Container window isn't already open, hover over the edges of your guide in the Visual Design Studio and select the blue highlight that appears around it. From here, you can edit the following:

• Element selection. Reselect, expand, or refine the CSS selector for the element that your guide is embedded into. This must be done from the first step of your guide.
• Position in element. Choose whether to prepend, append, or replace the content of the selected element for your embedded guide. This must be done from the first step of your guide.
• Page location. Choose to display the guide on every page in your application or only on a specific page in your application. You can do this for each step in your guide individually.
• Settings. Ensure that the CSS selector of the element that you're embedding your guide into is stable by keeping Filter Dynamic Elements on Selection turned on. This setting applies to all steps in your guide universally.

Select Done in the bottom-right corner of the Edit Container window when you're done editing these location settings.

Position on page

An embedded guide is part of the page in your application and is always positioned inside the selected element on the page.

Element selection

You can reselect the element that your guide is embedded in. This must be done from the guide's first step. 

To reselect the element your guide is embedded in, select Clear Selection in the Select Element section of the Edit Container window and choose another element. You can then either keep the Suggested Match or:

• Expand your selection to a larger element using the Parent Element option.
• Refine your selection using the Custom CSS option. For guidance, see Using CSS rules for guide targeting.

Position in element

You can choose where to position the embedded guide inside your chosen element. This must be done from the guide's first step.

Under Position In Element, choose between:

• Prepend. Places the guide at the top of the element. This is typically the left-most position in a row or the top position in a column.
• Append. Places the guide at the bottom of the element. This is typically the right-most position in a row or the bottom position in a column.
• Replace. Replaces the element’s existing content with the guide. We recommend that you only use this option if you have a background image in the container that you're using to target your embedded guide. You can't use this option if you're selector uses a contains rule.

To avoid layout shifts, we recommend placing an embedded guide inside a placeholder container and using Replace. For recommendations about choosing an appropriate element for your embedded guide, see Guides overview.

Page location

Under Page Location, choose whether the guide step shows:

• Sitewide. The guide content shows on all pages in your application where the element that you embed the content into is present.
• Only on this page. The guide content shows on a specific page in your application. If you haven't tagged the page that you want the guide content to show on, follow the instructions in Page tagging.

Settings

Turning the Filter Dynamic Elements on Selection setting on or off in any step of an embedded guide turns it on or off for all steps in the guide.

We recommend keeping the Filter Dynamic Elements on Selection setting turned on. This ensures that the CSS selector you embed your guide into is a stable identifier that's unlikely to change over time.

Step 3. Add guide content

There are multiple guide building blocks that allow you to add and format text, buttons, images, polls and embedded videos. For more information, see Add and edit guide content.

First, ensure you're in the right step of your guide. If the steps of your guide aren't visible, select the View Steps tab of the Visual Design Studio toolbar. From here, hover over the step that you want to add content to and select Edit Step.

Then, add and edit your building blocks to add content. For instructions, see Add and edit guide content. For information about building blocks that you can add to an embedded guide and how to edit them, see Guide building blocks.

Tip: Periodically save your changes as you edit your guide to save your progress.

Step 4. Add steps (optional)

If you want to include more embedded content in the same location, you can add steps to your guide and configure buttons in each step to allow the visitor to move through the content.

If the steps of your guide aren't visible in the Visual Design Studio's toolbar, select the View Steps tab. You can then add more steps:

1. In the toolbar of the Visual Design Studio, select + Add Step.
   
   
   
   
2. Follow the instructions in Add guide content in this article for your new step.
3. Add a button to each step with an action of Next Step. For information about button actions, see Guide button actions.

Step 5. Edit styling

Embedded guide styling is edited in the Styling tab of the Edit Container window. If the Edit Container window isn't already open, hover over the edges of your guide in the Visual Design Studio and select the blue highlight that appears around it.

If you have more than one step in your embedded guide, you must edit the styling for each step individually. From the step tray in the Visual Design Studio, hover over the step that you want to edit and select Edit Step. Then, open the Styling tab of the Edit Container window.

From here, you can edit the following:

• Theme. The saved styling of the layout and building blocks for your guide.
• Container settings. The name, close button, and dimensions of your guide. If you choose Custom as your Theme, you have additional styling options available to you.
• Accessibility. The ARIA labels in your guide and WAI-ARIA role for your guide.

Theme

Theme defines the saved styling of the layout and building blocks for your guide. For information about guide themes, see Manage guide styling with themes.

If you choose Custom as your theme, you have more styling options available to you for that step in your embedded guide.

Container settings

As standard, the Container Settings allow you to do the following:

• Add a name to the step in your embedded guide.
• Choose whether you want to add a close (X) button to the step in your guide. If you add a close button to your guide, you can edit its color, spacing, and top-left or top-right alignment. For instructions, see Guide building blocks.
• Choose the width of your guide:
  • Select Full width if you want the guide to cover the full length of the element that your guide is embedded in.
  • Select Fixed if you want the guide to stay at a fixed size regardless of the size of the element that your guide is embedded in. The Width of a fixed embedded guide is set in pixels (px).
• Choose the height of your guide:
  • Select Auto height (default) if you want the guide's height to adjust based on the content you add to it.
  • Select Full height if you want the guide's height to be the same as the element your guide is embedded in.
  • Select Fixed height if you want to specify the guide's height in pixels (px).

If you choose Custom as your Theme, you additionally have the option to:

• Edit the Margin of your guide step. This is the space in pixels (px) between the guide's container and the neighboring elements on the page. You set the margins from the Top, Right, Bottom, and Left individually.
  
  
  
  
• Edit the Padding of your guide step. This is the space in pixels (px) between the guide's contents and the edges of the guide container. You set the margins from the Top, Right, Bottom, and Left individually.
  
  
  
  
• Edit the guide step's Border Color, Width, and Radius (corner roundness). The border color is set with a hexadecimal, RGB numbers, visual color selector, or color slider. The Width and the Radius are set in pixels (px).
  
  
  
  
• Edit the guide step's Drop Shadow Color (and transparency), angle (X), distance (Y), softness (Blur), and size (Spread). The color and transparency of the drop shadow is set with a hexadecimal, RGBA numbers, visual color selector, or color and transparency sliders. The X, Y, Blur, and Size of the drop shadow is set in pixels (px).
  
  
  
  
• Edit the order of the guide step's container for overlapping elements in the UI. The higher the Z-Index, the further forward in the UI the element is. Only change this if your guide is hidden by something with a higher z-index, such as a modal or your backdrop.
  
  
  
  
• Edit the Background. The color and transparency of the background is set with a hexadecimal, RGBA numbers, visual color selector, or color and transparency sliders.
  
  

Accessibility

For the benefit of screen readers, you can edit the following:

• The ARIA Label - Accessible Name, which is the alternative name for your guide step, read by screen readers.
• The Role, which is the semantic meaning assigned to your guide step. For information about ARIA roles, see Mozilla's WAI-ARIA roles.
• The ARIA Label - Close Button, which is the alternative name for your guide's close button if you choose to include it, read by screen readers.

Step 6. Configure guide activation

Embedded guides are always activated automatically. Ordering and throttling settings don't apply to embedded guides because the content in embedded guides is always visible when the element that the guide is embedded into is present on the page. 

However, you can configure repeat guide display settings and choose which devices the guide should display on from the Activation Settings window of the Visual Design Studio.

• If you're still creating your embedded guide in the Visual Design Studio, hover over the Activation card before the first step of your guide and select the edit icon, or select the Activation shortcut next to the Navigate shortcut at the top of the toolbar.
  
  
  
  
• If you've already created a guide, open the Settings tab of your guide in Pendo and select Manage in my app from the top-right corner of the Activation card. This opens the Visual Design Studio over your application with the Activation Settings window open by default.
  
  

Repeat guide display

Repeat guide display is only relevant if you add a close button to your embedded guide. The close button is added from the Styling tab of the Edit Container window. For more information about the close button, including how to edit its appearance and position, see Guide building blocks.

When you turn Repeat Guide Display on, you must complete the following:

1. In the Repeat Every field, enter the interval (number of days or hours) before the guide automatically displays again to eligible visitors. The repeat interval starts when the visitor sees the guide. You can set the interval to a number between 1 to 10,000, then choose either Day or Hour.
   
   
   
   
2. Set the expiration to limit how many times a visitor sees the guide at the repeat interval. Choose the Expiration Type:
   • If you choose Never, the guide shows again at the repeat interval until the guide is turned off or the visitor is no longer in the guide's segment.
     
     
     
     
   • If you choose A set number of dismissals, enter how many times an eligible visitor must dismiss an automatic guide before it expires for the visitor. The minimum is two dismissals.
     
     

Choose devices

The options under Show Guide On allow you to choose whether to show the guide on specific device types. Choose between the following three options:

• All devices
• Desktop & tablets only
• Mobile only

Step 7. Save and preview your guide

When you're done creating and editing your guide:

1. Select Save and then Exit in the top-right corner of the Visual Design Studio toolbar. This saves your guide, closes the Visual Design Studio, and opens the details of your guide with the Settings tab open by default.
2. From the Settings tab of your guide, select Preview. This opens your embedded guide in a new tab in your browser.
3. Select Exit preview from the Visual Design Studio toolbar when you're done.

Next steps

After creating and previewing your guide, you can test, segment, schedule, and publish it. For instructions, see Test and deliver your guide.