A multi-page product tour is one tour whose steps belong to different pages. Each step can have its own page rule. The SDK saves where the visitor is, so the tour carries on after a page change, in another tab or on another device once the person is identified.
This guide explains how to set the pages, what happens when a visitor leaves, and how to read the results.
Why use one tour across pages?
Real tasks span screens. A user creates a project on one page, invites a teammate on another and sees the result on a third. Three separate tours need three triggers and three completion records. One tour keeps a single story and a single result report.
How do you put a step on a page?
Open the step's Pages, targets and completion section. Two settings matter.
Same page as the step before. This is the default. Switch it off to give the step its own page rule. The operators are:
- is exactly
- starts with
- contains
- matches pattern, where
*is one path segment and**is any depth - regex
For example, a pattern like /projects/*/settings matches the settings page of any project.
Button takes the visitor to. Enter a path or URL. When the next step is on another page, this step's button goes there. Button text when it leads to another page replaces the button label, for example "Go to settings".
Until the visitor is on a matching page, nothing shows. When they arrive, the tour continues from that step.
What does the SDK need on each page?
Call init() on every page, or use trackRouteChanges: true in a single-page app, so the SDK can check again after each navigation.
import { init } from "@justonecx/sdk";
await init({
publicKey: "pk_your_workspace_key",
apiUrl: "https://api.justonecx.com",
trackRouteChanges: true,
});
Calling init() again is safe. A tour already on screen is not fetched and shown a second time. For a site without a bundler, the script tag on every page does the same job. Add data-track-route-changes="true" if the site navigates on the client. Framework setups are on the frameworks page.
What happens if the visitor leaves in the middle?
A multi-page tour that is interrupted by navigation is paused, not dismissed. Its place is saved.
A tour with no per-step pages still counts a navigation away as dismissing it. That matters when you plan a tour. If the steps are on different pages, give each step its page rule. Otherwise a click on a link ends the tour.
Dismissing and finishing are different. Finishing or dismissing a tour marks it as seen, and it is not shown again automatically. A pause does not.
Where is progress saved?
On the server, for each person. The SDK saves the current step and what happened on each step. That lets a tour resume after a reload. It follows the person to another browser once they call identify(). When a person returns after a while, the tour continues from where they stopped.
Call identify after sign-in:
window.JustOneCX.identify("user-42", { plan: "growth", role: "admin" });
To start one person over, use Start one person over in the tour's Results tab, or Restart next to a tour in a customer's Insights in the chat inbox. Read more about the call in how to identify users with the SDK.
How do you keep steps working when the page changes?
A tooltip finds its element by selector first. It can list more ways, tried in order: visible text, an ARIA role with an accessible name, a data-jcx anchor, or a CSS selector. Text and role targets keep working when generated class names change. A tooltip needs at least one of these.
If the element is not on the page yet, the SDK waits for it. The wait is 5 seconds by default and up to 30 seconds per step. If it never appears, the step is skipped, the skip is recorded, and the tour finishes as finished with skips. The builder marks such steps "never saw it".
Can a step wait for the user to do something?
Yes. Steps can finish on a button click, a click on the element, or an event. An event can also be required to come from your server only. See server-confirmed steps.
You can also mark a step Required. When a visitor closes it, they pick a reason first. Set the list in the tour's Settings tab, Targeting section, Skip reasons. The defaults are Not relevant, Already done and Later. The reasons appear per step in Results.
How do you read the results?
The Results tab shows:
- Started, finished, finished with skips, and abandoned (no activity for 7 days).
- The biggest drop-off, with its page.
- A per-step table: reached, skipped by reason, target missing, median time.
- A split by any user trait you send with
identify(), for exampleplan.
The page shown with the drop-off tells you whether people stop on a page or while moving between pages. If many steps show target missing on one page, the page rule or the target needs a fix.
For design advice, read product tour best practices. Targeting details are in targeting and segments. The full guide is multi-page tours.
Frequently asked questions
Is a tour dismissed when the visitor navigates away?
Not if its steps have per-step pages. It is paused and its place is saved. A tour with no per-step pages still counts a navigation away as dismissing it.
Does progress follow the user to another device?
Yes, once they identify(). Progress is kept on the server for each person.
How do I restart a tour for one person?
Use Start one person over in the tour's Results tab, or Restart in the customer's Insights in the chat inbox.
Do I need init on every page?
Call init() on every page, or use trackRouteChanges: true in a single-page app.
See how it works in the live demo.