Overview
Engagement Guides guide users to discover new features or adopt existing ones. Based on the complexity & importance of the feature the prompt is referring to, different guides should be used.
Quick guide
|
In-app guide type |
Announcement type |
|---|---|
|
Modal |
Critical product announcement |
|
Non-modal dialog |
Product changes, beta availability, New features announcements |
|
Guide |
First-time user, New feature walkthrough |
|
Popovers |
Feature callout, element relocation, hidden settings |
|
Feedback badge and modal |
Feedback |
#pendo-guide-container {
font-family: 'Sofia Pro', sans-serif !important;
}
.pendo-radio {
font-family: 'Sofia Pro', sans-serif !important;
}
[id^="pendo-image"] {
border-top-left-radius: 8px;
border-top-right-radius: 8px;
}
._pendo-button-primaryButton {
box-shadow: 0px 1px 2px 0px rgba(0, 0, 0, 0.25), 0px -1px 0px 0px rgba(0, 0, 0, 0.10) inset, 0px 1px 0px 0px rgba(255, 255, 255, 0.35) inset;
}
._pendo-button-secondaryButton {
box-shadow: 0px 1px 1px 0px rgba(0, 0, 0, 0.06), 0px 0px 2px 0px rgba(0, 0, 0, 0.06), 0px 0px 1px 0px rgba(0, 0, 0, 0.08);
}
._pendo-step-container-styles, {
box-shadow: 0px 24px 32px 0px rgba(0, 0, 0, 0.04), 0px 16px 24px 0px rgba(0, 0, 0, 0.04), 0px 4px 8px 0px rgba(0, 0, 0, 0.04), 0px 0px 1px 0px rgba(0, 0, 0, 0.20) !important;
border: none !important;
}
li {
margin-bottom: 8px;
}
Popovers
Popovers are small windows that appear next to the feature or element they are related to. They often contain a short message and a dismiss button.
Use popovers to provide contextual information and guide users to specific features or elements. They are also useful for providing information that users might not know about, such as a re-located or hidden setting.
Styling
- Popovers should not use a background overlay
Content
|
Content |
Description |
Example |
|---|---|---|
|
Title (required) |
Describe the step, sentence case |
Looking for the support chat? |
|
Body |
Short and concise direction (1-2 lines max). Bold high priority points. Sound like a human not a robot. |
It’s up here now! |
Placement
- Position on page should be Relevant to Element and position to element to Auto
Examples
Guides
Guides are step-by-step prompts that lead the user through a feature or process. They often include a combination of text, images, and interactive elements.
Use walk-throughs when introducing a new feature, onboarding new users, or when significant changes have been made to an existing feature.
Styling
- Ensure show target element above backdrop is checked ON
- Expandable click area should be set to 4px
Content
- Instructions should be concise and clear of verbose descriptions. Link to a support article for more explanation on a particular step
- Avoid adding critical information in the guide as it may not be seen again after the marketer has completed the guide.
|
Content |
Description |
Example |
|---|---|---|
|
Subtitle (step count) |
Include current step & total number of steps |
1 of 5 |
|
Title |
Describe the step, sentence case |
Configure your campaign content |
|
Body |
Short and concise direction (2-3 lines max). Bold high priority points. Sound like a human not a robot. |
Select a previously created template, or start from scratch to add content to your campaign. |
|
Actions |
Allows the marketer to move to the next step or exit the guide |
Primary: Next Tertiary : End tour |
|
Actions (final step) |
The final step in the guide, allowing the marketer to close the guide. |
Primary: Done |
Placement
- Position on page should be relevant to element
- Position to element should be set to Auto
Examples
Modal
Modals are windows that appear in front of the main interface and require user interaction before they can be dismissed. They often contain a message, information, or form fields.
Use modals when you need to gather user input, provide important information, or confirm an action before it is taken. They are also useful for blocking the user's access to the application until they have taken a necessary action.
Styling
- Autofocus on element option should be disabled
Content
|
Content |
Description |
Example |
|---|---|---|
|
Title |
A brief title describing the announcement |
Coming Soon: Updated Snippets |
|
Body |
A description on the announcement. |
As part of the new Aurora User Experience, we’re giving Snippets a new look and feel. What’s new: - Sleek new page layout: Create, edit, and manage your snippets faster than ever.
Look for this update in the next few weeks! |
|
Actions |
If available, a Learn more action can be included in the footer to link to additional documentation. |
Primary (optional): Learn more Tertiary: Dismiss |
Placement
- Modal should be centered on page
Examples
Non-modal dialog
Non-modal dialog are small messages or notifications that appear at the bottom of the screen. They often contain a short message and a call-to-action button.
Use non-modal dialog to provide updates on product changes, beta availability, to announce new features, or to provide alerts or notifications.
Styling
- Ensure that you’re using the Aurora theme and don’t see “Custom” styles when selecting elements of the announcement
Content
|
Content |
Description |
Example |
|---|---|---|
|
Subtitle (Overline) |
A category describing the announcement type |
✨ New✨ / ‘Coming soon’ / ‘Beta available’ |
|
Title |
A brief title describing the announcement |
Campaign Performance Alerts |
|
Body |
A short, concise description on the announcement. Leave lengthy descriptions for documentation, or use a guide once the user has navigated the feature to provide explanations in context. |
Get notified if a campaign doesn’t perform as well as expected, prompting you to log in an troubleshoot the issue. To create and manage alerts for your project, you'll need the Manage Project Settings permission. |
|
Actions |
These single-step announcements should always use the primary button to close the dialog. If applicable, a secondary button can be included with links to supporting documentation. |
Primary: Okay, got it! / Done |
Placement
- Non-modal dialogs are placed in the bottom-right corner by default, with a 24px margin from the perimeter of the screen.
- If they are relatively small in nature and relate to a visible UI element on the screen, they can be placed close to the element itself.
Examples
Feedback badge & modal
A feedback badge can be added to pages to collect localized feedback about a newly released feature or update. Clicking the feedback badge will open a modal that allows the marketer to provide feedback.
Feedback for the guide can be found in the guide’s “Poll responses” tab within Pendo.
Styling
- Feedback modals should include an overlay.
- It’s best to clone an existing feedback guide to retain the styling and then update the copy to fit the appropriate area.
- Do not modify the styles or content of the trigger badge.
Content
|
Content |
Description |
Example |
|---|---|---|
|
Badge text |
The badge that triggers the feedback modal |
👋 Feedback? |
|
Title |
A title for the modal |
How can we improve? |
|
Placeholder |
A placeholder inside of the text area |
Share your thoughts on the new {featureName} experience… |
|
Actions |
A single primary button to submit the feedback |
Primary: Submit feedback |
Placement
- Feedback badges should be placed next to the breadcrumb, if available
- Feedback badges can be be placed in one of the corners of the UI if no breadcrumb is available, but should not obstruct existing UI elements
Examples
Best practices
Segments
Segments used in guides should be mindful of a marketer's familiarity with Iterable. For example, if the position of an important action is moved, communicating that change to marketers that have previously used the feature can help them quickly find it. At the same time, showing that message the first time a marketer enters this section of the application adds unnecessary cognitive load.
By leveraging Pendo's segments tool, we can create a specific cohort of marketers that would receive this message—particularly those who may heavy users of the action.
Examples
|
Chat button re-located on Feb 1 |
Segment to all users that logged in prior to Feb 1 |
|
Improving on an existing feature |
Segment to users where 'First visit' was not within the last 30 days |
|
A new beta available |
Segment to users that have used function at least 10 times in the last year |
Expiration dates
To prevent outdated guides piling up in our app, all guides should include an expiration date / time.. For most guides, that end date should be 6 weeks from enablement. However, for longer beta periods, guides can have longer duration.
Testing
Some things to consider while testing the guide:
- Be sure to review all styles and fonts and ensure that they match the templates linked
- Ensure that the proper segmentation and schedule is set for the guide
- Always add an expiration date to the in-app guide and message
- Ensure that focus trap is not set on modal dialogs
Ensuring styles are correct
A custom Aurora theme has been created in Pendo to align as close as possible to Aurora styles given the customization options available. A few things to consider when preparing for sign-off:
- Check that all fonts use Sofia Pro, the Sofia font. Sometimes the legacy Open Sans font can appear if an outdated Pendo is copied without new styles applied
- Ensure there is appropriate spacing between form elements or buttons; Aurora follows an 8px grid and using a spacing number that is divisible by 8px will ensure that the pendo guides follow the existing spacing cadence in the app.
- Advanced: In some unique cases, Pendo may not allow the user to style specific elements. However, it is possible to override these styles with custom css.
- First, find the specific class you’d like to override using the dev console in your browser.
- Adding a custom code block (this can be placed anywhere—it will not appear on the actual guide when published)
- Navigate to the CSS tab, and add the custom CSS for the specific element or class name you found using the dev console. You should see the style updates change in real-time.
#pendo-guide-container {
font-family: 'Sofia Pro', sans-serif !important;
}
.pendo-radio {
font-family: 'Sofia Pro', sans-serif !important;
}
An example of updating the Ranking element in Pendo guides to use the correct font and hover styles. Applying the #pendo-guide-container font-family attributes for Sofia pro ensures that all the font used within the guide is correct—even if legacy styles are applied.
Additional resources
- The Announcement component can be used for critical messages that may impact system status—such as a maintenance period
- A Banner can be used to provide conditional or temporary messages the marketer, but must be hard-coded into the interface
- A Toast can be used to provide feedback to the marketer, but is generally visible after an action is taken within the product