Create an embedded guide

Embedded guides display inline within your application's content rather than appearing over it as a popup. Because they flow with the rest of your page layout, they're well-suited for contextual messaging that should feel like a natural part of the experience.

Use embedded guides to deliver content that's informational, recurring, or segment-specific, such as:

• Routine notices. Deliver server maintenance alerts, updated terms of service, or privacy policy changes without covering key navigation.
• Contextual form guidance. Provide extra information to visitors filling out a form, targeted to specific segments.
• Feature and event announcements. Promote new features, upcoming events, or webinars on login pages or your homepage.
• Action reminders. Remind visitors of tasks they need to complete by a specific date.
• Persistent in-app messaging. Create a designated space for information that might otherwise be buried elsewhere in the application.

For step-by-step walkthroughs, element-specific guidance, or content that requires visitor attention, consider using a tooltip or lightbox guide instead.

Prerequisites

You must have the correct role permissions to create or edit guides.

Step 1. Create an embedded guide

To start creating an embedded guide:

1. From the left-side menu, go to Guides > Guides.
   
   
    
2. From the top-right corner, select Create guide.
3. Choose the application where you want the guide to display.
4. Optionally, select a category for your guide. The category is used to organize the guide and to display recommended layouts.
   
   
    
5. Select Embedded to make your guide display inline within your application's content.
   
   
    
6. Find a layout for your guide. Layouts help you apply consistent styling to guides across your organization. If you have a large number of layouts available, use the category filter to narrow the list, or search by name.
7. Hover over the layout you want and choose Select layout.
   
   
   
   Note: The theme is applied through the layout. You can change it later in the Visual Design Studio.

Step 2. Name and organize your guide

1. Name your guide by selecting the default title at the top of the page and entering a new guide name.
2. Optionally, select a Product Area and category from the dropdown menus below the guide title. Product Areas and categories help you organize your guides. 

Step 3. Add and edit guide content

1. Select the guide you want to edit. 
2. From the Settings tab, select Edit in my app. 
   
   
    
3. 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 you want to add content to and select Edit Step.
   
   
    
4. Then, add and edit your building blocks to add 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 Guide building blocks overview. 

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

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.

1. You can add steps to your guide from the Visual Design Studio toolbar at the top of the page. If the steps aren’t visible, select View steps. Select + Add step, then choose a layout for the new step. 
   
   
    
2. Select the layout for your new step.
3. Add and edit your content.

Step 4. Edit location

To edit the location and position of an embedded guide, open the Location tab in the Edit Container window. 

If the Edit Container window isn’t open, open the guide in the Visual Design Studio and hover over the edges of the guide, then select the blue highlight that appears.

From here, you can edit the following:

• Select Element. 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 (Sitewide) 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. 

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 your selector uses a contains rule.

To avoid layout shifts, we recommend placing an embedded guide inside a placeholder container and using Replace. 

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. In order for the guide to show, you must tag the page. 

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

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:

• 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 Close (X) button building block.
• 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 width 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).

Styling a custom theme

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 values, 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 values, 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 values, 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. Set the guide display settings

Embedded guides display automatically when the page loads. The activation method is set to automatic and can’t be changed. However, you can adjust how the guide behaves for repeat views and which devices it displays on.

If you have already created the guide:

1. Open the Settings tab of your guide.
2. Scroll to the Activation card.
3. Select Edit 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.

If you're editing a guide in the Visual Design Studio, you can access the activation in either of the following ways:

• Select the Activation card from the toolbar, located before the first step of your guide.
• Select the Activation shortcut in the top-right of the toolbar, next to the Step Map.

This will open the Activation Settings window. 

Activation settings

In the On page load field, choose what happens when the page reloads. 

• Restart guide. Starts the guide from the first step.
• Show last step seen. Returns the visitor to the last step they viewed.
  
  

In the Show guide on field, choose where the guide should display:

• All devices. Displays the guide on both device types.
• Desktop & tablets only. Displays the guide only on desktop and tablets.
• Mobile only. Displays the guide only on mobile devices.
  
  

Step 7. Test your guide

Before publishing, test your guide by creating a segment that targets only you. This ensures the guide appears as expected without being visible to other visitors.

1. On the guide details page, locate the Segment tile and select the edit icon.
   
   
    
2. In the dropdown, choose the edit button over Custom Segment.
   
   
3. Add a segment rule where Visitor ID equals your own Visitor ID.
4. Select Save custom segment, then select Save within the Segment tile.
5. Set the guide status to Public.
   
   

Because the segment targets only your Visitor ID, the guide will only appear to you.

Step 8. Publish your guide

When you're ready to publish, update the segment to target your intended audience. You then have two options for publishing.

To publish your guide immediately, set the guide status to Public.

To schedule your guide:

1. On the guide details page, scroll down to the Scheduling card.
2. Select Edit.
   
   
    
3. Set a start date.
4. Optionally, set an end date to control when the guide stops being active.