To trigger a product tour on a button click, call startTour("tour-key") from your click handler. It plays the tour right away. You can also turn on the tour's persistent launcher, which shows a "Replay tour" button for you and calls startTour itself.
How do you call startTour?
Import it from the SDK and pass the tour's key or id:
import { startTour } from "@justonecx/sdk";
startTour("export-flow"); // the tour's key, or its id
Here it is in a React button:
import { startTour } from "@justonecx/sdk";
export function HelpMenuItem() {
return (
<button type="button" onClick={() => startTour("export-flow")}>
Show me around
</button>
);
}
The docs suggest exactly this use: a "Show me around" item in a help menu.
The SDK must have started first. Call init() once in the browser after your app mounts. See the init reference.
Where do you find the tour key?
Pass the tour's key or its id. The key is set when an AI assistant creates the tour, for example export-flow. The id is in the URL of the tour's edit page in the dashboard.
Only published tours start. If you call startTour with a draft, nothing plays. To test a draft, use Preview on your site, or a preview link, which plays the current draft for 24 hours on any page where the SDK runs.
What does startTour ignore?
startTour plays the tour immediately. It ignores the tour's targeting, frequency cap and completion state.
That has three effects:
- A user who finished the tour can run it again.
- A user outside the tour's audience can still run it, because they asked for it.
- The frequency cap limits only automatic playback. A manual replay always works.
If you want a button that only some people see, hide the button in your own code. Targeting does not apply to a manual start.
What is the persistent launcher?
Instead of writing your own button, enable the persistent launcher. Open the tour's Settings tab, then the Launcher section. A "Replay tour" button stays available after the visitor finishes the tour. You can set its screen corner. A visitor can dismiss it for good in their browser.
The launcher calls startTour for you. Use it when you want a replay option without wiring a button yourself. Use your own button when it belongs in a menu, a settings page or an empty state.
When should a tour start automatically?
Automatic playback fits moments where the user would otherwise get lost:
- The first visit after sign-up, targeted to new visitors.
- The first time someone lands on a page with a complex layout, set with a page rule.
- A new feature that every existing user should see once.
Set audience, pages and schedule in the tour's Settings tab. The server applies the audience before content reaches the browser, and page rules are checked in the browser on every page change. See targeting and segments.
Finishing or dismissing a tour marks it as seen. It is not shown again automatically.
When should a tour start on demand?
On demand fits help the user asks for:
- A "Show me around" item in a help menu.
- A button next to a feature that needs explaining, such as an export dialog.
- A link at the end of an announcement. An announcement can have a call to action that starts a tour.
- A help center Learn tab, which lists tours.
People who ask for help are ready to read it. People who get a tour they did not ask for often close it. A good pattern is to use both. Run a short tour automatically for new users, then leave the launcher on so they can replay it. More tips are in product tour best practices.
What if the button does nothing?
Check these in order:
- Is the tour Published? Only published tours start.
- Did
init()run? Open the console and look for[JustOneCX]messages. - Is the key or id spelled correctly?
- Is the target element on the page? If a tooltip's element never appears, the step is skipped and recorded. If no step in a tour can be shown, nothing displays.
Do not call init() on the server. The troubleshooting steps are on the troubleshooting page, and why a product tour is not showing goes deeper.
How do you pick the right trigger for each tour?
Ask who needs the tour and when. If every new user needs it once, play it automatically and target new visitors. If only some users need it, and they know when, give them a button. If you are unsure, start on demand: a button never interrupts anyone, and you can read the Results tab to see who uses it.
You can mix both. A manual start and the automatic start use the same tour, so you only maintain one set of steps.
What about sign-out?
Call reset() when the user signs out. It stops any tour still playing and removes launcher buttons, then starts a new anonymous visitor and runs init() again unless you pass remount: false.
import { reset } from "@justonecx/sdk";
await reset();
Frequently asked questions
Does startTour respect targeting?
No. It ignores the tour's targeting, frequency cap and completion state.
Can I start a draft tour with startTour?
No. Only published tours start.
What do I pass to startTour?
The tour's key, or its id from the URL of the tour's edit page.
Does the frequency cap block a replay?
No. It limits only automatic playback. A manual replay always works.
See how it works in the live demo.