My product tour is not starting

There are several reasons why your product tour may not be showing. Rest assured, we can solve it! Let's dive in.

If you just previewed the tour

If you opened this page from a Hopscotch preview link, the browser tab stays in preview mode until the tab is closed. In preview mode, Hopscotch suppresses automatic product tours so a published tour does not immediately start or repeat after the preview.

To test whether an active tour starts for a real visitor, close the preview tab and open your app in a new tab, browser window, or incognito window.

Check whether auto-start is turned on

If you expect a tour to start automatically, edit the tour and make sure Auto-start this tour is checked.

When auto-start is off, Hopscotch will not automatically show the tour based on URL, audience, frequency, or page element conditions. The tour can still be launched manually from a launcher item, a data-hopscotch-tour-id button, or the Browser SDK.

If you want a button-only or launcher-only tour, leaving auto-start off is expected.

Check page element trigger conditions

If your tour uses a Page Element condition, Hopscotch waits until that condition is met before starting the tour.

Confirm these items:

• The tour is active and saved.
• Auto-start this tour is checked.
• The page URL and audience rules match the visitor you are testing with.
• The CSS selector exists on the page when the condition should be true.
• For click triggers, the visitor clicks the element that matches the selector.
• For input triggers, the selector points to the input whose value should be checked.

For setup details, see Trigger product tours from page elements.

Check the CSS selectors

A common reason for tours being broken is if the CSS selector used to highlight an item

It is best-practice to use IDs because they are more likely to persist when your development team deploys a new version of your app.

CSS classes can also be used, but they tend to be more fragile.

How do I know if I am using a class or an ID?

1. Visit your tours page and edit the tour that is having issues
2. Click the Advanced settings button on the step that is having issues
3. Check the “point to element” input field. This will tell you which element your step is pointing at.
   • IDs start with a # sign. So you may have something like: #top-nav-bar-button
   • a class starts with a .. Example: .top-left-button-123

Pictured above: From the edit tour screen, click advanced settings to see the CSS selector used for your step

Pictured above: An example of a fragile selector. It is fragile because this selector was not hand-written and will likely be overwritten in a future build.

What makes a selector fragile?

A fragile selector may look something like: .xmjMuk, #input-115, or .items-collection:nth-child(3)

The main culprit for a fragile selector is when it is auto-generated. Generally these auto-generated selectors will be re-built on each change to your app, and so they may change entirely.

Examples of fragile selectors:

• .xmjMuk might become .yx4x6 the next time your development team makes a change.
• #input-115 may become #input-123 because of the order of items on the page.
• nth-child(3) refers to the third item in a list of elements, so you need to ensure this item will always be in the third position

What’s the solution to fragile selectors when building product tours?

• Use Handwritten IDs: Whenever possible, you should use hand-written IDs for your selectors. Your development team may need to add these IDs to the elements you want to showcase
• Use videos and images: If you don’t have the ability to change the IDs in your app, but you want to highlight items with fragile selectors, you can use videos or screenshots in your guides. Here is an example of a video tour to showcase a more complex workflow

If your element ID starts with a number, you will need to properly escape the ID

Element IDs starting with numbers must be properly escaped. You can read more here about how to properly escape these IDs.

Debugging tips

Here are some steps for debugging your selectors

• Check that your selector exists: (for developers)

  1. copy the selector from the Advanced settings screen (ex: .your-selector-123)

  2. Open chrome and visit the page of your app where you are having issues

  3. Open the JavaScript console

     

  4. type document.querySelector(".your-selector-123") and press enter (don’t forget the quotes). If the result is null, the element does not exist on the page.