Troubleshooting & FAQ

#The launcher doesn’t appear

Work down this list — it’s almost always one of the first four.

1. Is the script on the page? View source or check DevTools → Network for embed.js. Use Test installation on the site tile.
2. Is it the right site key? Each site has its own. Re-copy the snippet from the site tile.
3. Is the walkthrough active? Check the toggle on the walkthroughs list.
4. Does the page path match? /dashboard doesn’t match /dashboard/settings — use /dashboard/*. See Pages & screens.
5. Is a display condition failing? Device, dates, prior tours and element conditions all have to pass. Remove them one at a time to find the culprit.
6. Is another tour winning? Only one tour shows at a time per page. See several tours on one page.
7. Over your monthly views? The usage bar on the Sites page will be full. See limits.
8. Content Security Policy? Look for CSP errors in the console. See CSP.

#It doesn’t open automatically any more

Auto-open and auto-launch respect each visitor’s history: once they’ve clicked “Don’t show again” or hit the max-shows limit, it stays quiet for them. That includes you while testing. Use a private window or clear the ls- keys — see browser storage.

#A step is skipped

The step’s selector didn’t match anything when the tour got there. Test it in the console with document.querySelector('…'). If the element appears later (after a click or a fetch), point the step at something that’s already there, or split the tour. See Choosing selectors.

#The spotlight is on the wrong element

The selector matches more than one element and the first one wins. Make it more specific — ideally a data-tour attribute.

#It broke after a deploy

Generated class names change between builds. Replace class-based selectors with data-tour attributes.

#Auto-launch shows the welcome card instead

None of the tour’s step targets appeared within 8 seconds, so it fell back to the welcome card rather than run an empty tour. Check the selectors exist on that page.

#Apps

• No launcher: check TTLauncherView is at the root, the screen calls .ttPage() / useTTPage() with the same identifier as the walkthrough’s Screen, and the tour is active.
• Step doesn’t highlight: the view needs .ttTarget() / useTTTarget() with exactly the identifier in the step.
• Doesn’t scroll to the step: add the scroll helper for your layout — see iOS, Android, React Native.
• QR code doesn’t open the app: the URL scheme or deep-link handler is missing. See Visual Inspector.
• Can’t add an app site: app sites need the Too Many plan.

#FAQ

#Do I need a developer?

For websites, only to paste one line of code (and many site builders let you do that yourself). Everything else is in the dashboard. Apps need a developer for the SDK setup.

#Will it slow my site down?

No. The script loads asynchronously, doesn’t block rendering, and does nothing on pages without a tour.

#Do I need to mention it in my cookie banner?

Tooltip Tour sets no cookies and doesn’t identify visitors; it uses localStorage only to remember tour state. Check with your own adviser, but most sites treat this as strictly functional.

#Does it work behind a login?

Yes. The script runs in your visitor’s browser, so it works on any page they can see, including logged-in app pages. Only Test installation needs a public page.

#Can I translate tours?

Create one walkthrough per language and scope each with a page path (e.g. /fr/*) or an element condition on something language-specific.

#Can I target specific users or segments?

Not by user identity. Use an element condition on something only that segment sees — for example a [data-plan="trial"] attribute you render for trial users.