Product tour best practices: 7 mistakes and how to fix them

By Hasan · November 5, 2026 · 6 min read

Good product tours are short, point at the right element, talk about what the user wants and reach only the people who need them. Most bad tours fail on one of seven points: too many steps, wrong placement, copy about code, no targeting, no measurement, no replay and no preview. This guide goes through each one and shows the fix.

Mistake 1: Why do tours with too many steps fail?

Every step asks the user to stop what they came to do. After a few steps they close it.

Fix it by cutting the tour to the path that leads to the first result. If you have more to say, split it into several short tours, each on its own topic. A checklist step can hold the rest as optional tasks the user picks when ready. See how to build an onboarding checklist.

A step does not have to be a tooltip. The step types are tooltip, modal, banner, checklist and end. Use a tooltip only when you are pointing at something. Use a modal for a short welcome, and an end step to say what to do next.

Mistake 2: Where should a tour step point?

A tooltip step highlights the element found by the step's selector. If the tooltip covers the thing it explains, or points at an empty area, the user cannot follow it.

Fix it by checking three things:

  • Point at the element the user needs to touch, not at its container.
  • Choose the placement from where the element sits on screen. A tooltip near the bottom edge should open upward. A tooltip beside a left sidebar should open to the right.
  • Make the target stable. Besides a CSS selector, a tooltip can find its element by visible text, an ARIA role with an accessible name, or a data-jcx anchor. Text and role targets keep working when generated class names change.

The SDK scrolls the element to the middle of the screen before it places the tooltip, and it skips the animation when the visitor prefers reduced motion. If the element is not on the page yet, the SDK waits for it. The wait is 5 seconds by default, and you can set up to 30 seconds per step.

Mistake 3: Why should copy talk about the user and not the code?

"Use the export module to generate a CSV" describes your product. "Download your data as a spreadsheet" describes what the user gets.

Fix it with these rules:

  1. Start the sentence with a verb the user does.
  2. Name the outcome, not the feature.
  3. Keep it to one or two short sentences.
  4. Put the button label in the user's words: "Show me", "Next", "Got it".

Read each step aloud. If a person new to your product would not use that word, change it.

Mistake 4: What happens when a tour has no targeting?

A tour with no targeting shows to everyone, everywhere. That includes your power users, who will close it, and people on pages where it makes no sense.

Targeting has three parts. Audience decides who sees it, using segments, conditions and new versus returning visitors. Pages decide where. Schedule decides when, for tours. Leaving a part empty means no restriction.

Fix it by setting an audience and a page rule for every tour. The server applies the audience before content reaches the browser, so hidden content is never sent. Page rules are checked in the browser. Operators are is exactly, starts with, contains, matches pattern and regex. The builder has a Test a URL box that shows whether a URL would match. Details are in targeting and segments.

Segments need data. Send traits with identify:

window.JustOneCX.identify("user-42", { plan: "growth", role: "admin" });

Mistake 5: How do you measure a tour?

A tour you do not measure is a guess. Open the Results tab. It shows started, finished, finished with skips and abandoned. It also shows the biggest drop-off with its page, a per-step table, and a split by any trait you send with identify().

Fix it by reading the drop-off first. The step where people stop is the step to rewrite, move or remove. Then check whether the people who finished did the action you wanted. Results are only as useful as your events, so decide the action first. See how to pick your activation event.

Note that a step whose element never appears is skipped and recorded, and the tour ends as finished with skips. The builder marks such steps "never saw it". Treat those as bugs.

Mistake 6: Why does a tour need a replay option?

Finishing or dismissing a tour marks it as seen, and it is not shown again automatically. Someone who clicked through too fast has no way back.

Fix it by enabling the persistent launcher. In the tour's Settings tab, open the Launcher section. It shows a "Replay tour" button that stays available after the visitor finishes. You can set its screen corner, and a visitor can dismiss it for good in their browser. You can also build your own button with startTour. See how to trigger a tour on a button click.

Mistake 7: What goes wrong when you skip the preview?

Publishing without a look means the first real user finds the broken step.

Fix it with Preview on your site. It uses the JustOneCX browser extension to play your draft on your own live page. Preview links also exist. A link with a jcx_preview token plays the tour's current draft for 24 hours on any page where the SDK runs, and nothing else from your workspace shows on that page.

Check the tour at a narrow window width, with the page loaded fresh, and as someone who is not signed in.

A short checklist before you publish

  • The tour is 3 to 5 steps, or split into smaller tours.
  • Each tooltip points at the element the user touches.
  • Copy names the outcome.
  • Audience and page rules are set.
  • You know which action counts as success.
  • The launcher is on.
  • You previewed it on your own site.

Frequently asked questions

How many steps should a product tour have?

The docs do not set a limit. Keep it to the path to the first result and split anything longer into separate tours.

What if the element is not on the page?

The SDK waits for it, 5 seconds by default and up to 30 seconds per step. If it never appears, the step is skipped and recorded, and the tour finishes as finished with skips.

Does the frequency cap stop a manual replay?

No. The frequency cap limits only automatic playback. A manual replay always works.

Can I stop a tour from showing on some pages?

Yes. Use page rules in targeting, or the excludePaths option in init() to hide everything from JustOneCX on a path.

See how it works in the live demo.

See it working in 2 minutes

Try the live demo

Related