Create a mobile guide

This article outlines how to create a guide for a mobile application using the Visual Design Studio.

Requirements

To use the Visual Design Studio, you must:

• Be a subscription admin, or
• Have guide editing or publishing permissions.

Step 1. Create a guide

1. Ensure that the mobile application is integrated with SDK 2.x. An admin can verify this by going to Settings > Subscription settings. An Integrated label should be visible on an integrated app. 
   
   
    
2. In the left-side menu, go to Guides > Guides.
3. In the Guides page, select Create guide.
4. Select the relevant mobile app from the dropdown menu.
   
   
    
5. Select your preferred guide layout, or use one of the AI-assisted options if you have Guides Pro.

Step 2. Add guide content

After you create the guide, in the guide's details page, name it by selecting the default name in the top-left corner. Optionally, assign a Product Area and guide category using the dropdowns below the guide name.

Tip: As you'll most likely have multiple guides, it’s best practice to set naming conventions and use groups for easier searches.

Next, select Edit in my app in the top-right corner of the Content section.

Edits to the guide can be made from within the Edit Container box. The container's default settings are set by the app's theme.

1. To edit the container settings, change the theme to Custom.
2. After the initial edits are made, select Done.
3. Hover over the placeholder items within the guide preview and select to edit.
4. To add a new building block to the guide (button, title, image, text, poll, etc), hover between items until a blue line displays.
5. Select + to add a building block.

Step 3. Choose guide transition animation

Select how a guide transitions in and out of each step.

To change the transition, go to Edit Container > Transitions > Animations Type and select animation type, duration, and direction where applicable. In addition to the default transition type, which is None, you can also select Fade, Pop, or Slide.

Tip: For multi-step, full-screen, or pop-up guides, we recommend using the slide animation.

Note: Transitions currently aren't available for tooltips. 

Step 4. Activate your guide

When creating a guide, you need to decide how it will be activated.

Available activation options can be found in the action bar in Activation Settings.

App launch

The guide launches after your mobile app is opened. Ideal for survey guides and announcements that aren't page-specific, such as new user onboarding or showing what's new on the new app version. The guide is launched to segmented visitors as soon as the startSession method is called and the mobile session starts. 

• Repeat Guide Display. Shows a guide to a visitor ‌even if they've completed or dismissed it.

Page view

The guide launches after your visitor goes to a specific page in your app. Ideal for page-specific onboarding or Feature announcements that are page-specific, such as guiding new visitors on a specific page in your app, or notifying visitors that a specific screen is under maintenance. Select the pages in the app where the guide appears. Either select an already-tagged Page or tag a new Page by selecting the Tag New Page button. In this case, a device must be connected to capture a new Page. For more information, see Connect a mobile device. If you select multiple pages, the guide is activated when one of them is viewed for the first time.

Note: Different guide steps can have different pages set for activation. Deep links or organic user navigation with tooltips are recommended to direct the user to the next step in the guide on a different Page.

Target element

The guide launches after a visitor selects a specific Feature in your app. Ideal for Feature-specific onboarding, Feature-specific surveys and activating your Help Center. The mobile app doesn't support the option to activate a guide from a badge.

After selecting the desired Page, select an element that'll activate the guide by selecting it in the screenshot. If the UI element hasn't been saved, you'll be prompted to save the new UI element. 

Track Events

The guide displays based on one or more Track Events. This is ideal for showing a guide after a process completes or for troubleshooting when a user receives a specific server response.

There are two ways to activate a guide using Track Events:

• Track Event activation: When you select Track Events as the activation type, you're taken directly to the Track Events Settings page. Select one or more events to launch the guide. The guide displays when any of the selected events occur. Use the OR option to include multiple events.
• Track Event property activation: Use property-based logic to define when the guide appears. Select the property type, operator, and value. Use the OR option to include multiple property conditions.

See Track Events for more information.

Launch guide from guide 

To launch a guide from another guide, you don't need to set a specific activation method. You can leave all activation methods unselected. This option can also be combined with other activation methods. 

Step 5. Test the guide on a device 

It's crucial to test how the guide looks on an actual mobile device prior to publishing because the Visual Design Studio provides a web preview of the guide. 

To test the guide, select Test.

Note: If your device isn't connected, you'll need to connect your device. For more information, see Connect your mobile device.

During the test, Pendo disregards segments and throttling rules and shows the guide each time. Any target elements, pages, and activation methods specified in the guide must be present for this preview method.

After you finish working on the guide, save your changes using the top-right Save button and select Exit to leave the designer, or select the dropdown icon next to Save and choose Save and Exit.

Step 6. Segment and schedule the guide

When you’re satisfied with your guide, go to your guide’s details page to adjust the guide’s segment and scheduling.

• Select the segment of visitors who'll receive the guides. The default segment is ‘Everyone’. You can see how many users are included in your selected segment and the number of eligible visitors.
• Schedule when your guide will go live (and, if needed, when it'll no longer be active).

There may be instances when the number of eligible visitors is smaller than your segment. This may be because some of your users are still using an old app version with an old SDK version. In this case, Pendo's new features may not be available to these users.

Important: Guide segments include visitors who have been excluded from analytics unless they're explicitly excluded in the segment. 

Step 7. Publish and validate the guide

To publish your guide, update the guide’s status to Public. Because there is no staging option for mobile guides, never publish a mobile guide without testing its full flow on a mobile device. If you're included in the guide segment and want to see the guide on your device after publishing, you'll need to:

1. Disconnect your device from Pendo by selecting the Pendo FAB on your device and then selecting Exit pairing mode.

2. Close your app and relaunch it (guides are sent to the device at the beginning of the "session").

3. If you are included in the guide's segment, you'll be able to see the guide in your app by triggering the guide's "activation" criteria.

4. Note that after a user views the guide, they won't see it again unless it's set to "show every time".

Edit an existing guide in the simplified editor

You can update an existing guide in a simplified editor by selecting Edit in Pendo from the guide’s details page.

In this editor, you can:

1. Edit text and button content by selecting the text directly in the guide.
2. Undo recent text changes by selecting the arrow icon that appears. This option disappears after you move focus away.
3. Add a new step by selecting the + icon below a guide step, then apply a layout.
4. Duplicate or delete steps by hovering over a step and selecting the relevant icon.
5. Update the guide theme by selecting the Theme dropdown in the top-right corner.

When you're done, select Save guide in the top-right corner of the page to apply your changes.

Note: If you have Guides Pro with AI guide creation turned on for your subscription, the Guides AI agent appears on the left side of the editor. You can use it to suggest text changes, adjust tone, and perform other edits using natural language. For more information, see Create a guide using conversational AI.

For advanced guide settings, such as styling, activation, or targeting, select Edit in my app from the guide's details page to open the Visual Design Studio instead.

Frequently asked questions

Why isn't my guide displaying after it's been made public?

Regardless of the activation type of your guides, your application can only determine if an end-user qualifies for a new guide if that guide is included in the guide payload. The payload updates only when one of the following occurs:

1. startSession is called.
2. By default, the application is left in the background for 30 minutes or longer. This time period can be configured for each app. Contact our support team if you want to change the default configuration.  

As such, because startSession is usually called when you close your app and reopen it (though your developers determine when it's called, so this might not hold true for your app). We recommend trying to close your app, reopen it, and then activate your newly published guide. If this doesn't work, you might need to reach out to your developers to get clarification on when startSession is called or contact our support team.

Should I use the same API key in both test devices and production environments?

While not mandatory, it's recommended to replicate the exact customer experience, unless testing for a future release. Mobile apps use the same API key in testing and production (unless you create a separate development application in Pendo), and there won't be a distinction in the data collected if you do use the same API key. This can affect your analytics. However, you do have the option to utilize the exclude list to filter your own data from analytics. If you need an API key for each development and production environment, contact your Pendo account representative.

Can I test a mobile guide with only an IP address?

Currently, there's no native solution to do this. You can create a test segment that segments users to the development app version.

What counts as a guide being dismissed and not eligible to show again?

In some cases, your users may put your app in the background on their phone by pressing the home button on Android devices, or swiping up or touching the ID button on iOS devices. When this happens, if a guide is displayed, it won't be dismissed and is expected to reappear when the app is launched again. Your guide is considered dismissed (and not expected to show again) when selecting a button with a dismiss action, selecting the x buttons in the corner, completing the last step of the guide, or by closing the app.

Note: Selecting the Back button on an Android device dismisses pop-up guides.