To add a product tour to a React app, install @justonecx/sdk, call init() once in the browser after the app mounts, pass trackRouteChanges: true, and call identify() after sign-in. You then build the tour in the dashboard and publish it. The SDK fetches published tours on init() and plays the ones that match the visitor.
This guide shows the code from the docs and the steps to get a first tour on screen.
What do you need before you start?
- Your public key, which starts with
pk_. Find it in Settings, then Developers, in the dashboard. - Your site's origin added in Settings, Developers, Domains & CORS. For local work add
http://localhost:3000, or your dev port. - The package:
npm install @justonecx/sdk.
The public key is safe in the browser. The secret key is for your server only and never goes in React code.
How do you add the SDK to React?
Every framework follows three rules:
- Call
init()once, in the browser only, after the app mounts. - In a single-page app, pass
trackRouteChanges: true. The SDK then re-runs on each client-side navigation, so page targeting stays correct. - Call
identify()after sign-in andreset()on sign-out.
Here is the component from the docs:
import { useEffect } from "react";
import { identify, init } from "@justonecx/sdk";
const options = {
publicKey: "pk_your_workspace_key",
apiUrl: "https://api.justonecx.com",
trackRouteChanges: true,
};
export function JustOneCX({ user }: { user?: { id: string; plan: string } }) {
useEffect(() => void init(options), []);
useEffect(() => {
if (user) void identify(user.id, { plan: user.plan });
}, [user]);
return null;
}
Render <JustOneCX user={user} /> once, in your root component. The same code works for Remix and Preact.
Always set apiUrl. Without it the SDK calls localhost:8000 and logs a warning.
Why call identify?
identify tells JustOneCX who the user is. With it you can target a tour by plan or role, and progress follows the person to another browser. Traits merge, so call identify on every page load.
After sign-in, with a server-signed hash:
import { identify, reset } from "@justonecx/sdk";
async function onSignedIn(user: { id: string; plan: string }, userHash: string) {
await identify(user.id, { plan: user.plan }, { userHash });
}
async function onSignedOut() {
await reset();
}
The userHash comes from your server. Read identity verification before you go live, or the short version in how to secure identify with a user hash. For more on this call, see how to identify users with the SDK.
Call reset() on sign-out. Without it, a second user on a shared browser could inherit the first user's chat and other visitor state.
How do you create the tour?
- In the dashboard, open Tours and create one, from scratch or from a template.
- On the Builder tab, add steps. For a tooltip step, pick the element it points at.
- On the Settings tab, set targeting: who sees it and on which pages.
- Publish.
Drafts are never sent to visitors, so publishing is required. Open your app in a new browser window. The tour starts. You can also use Preview on your site, which uses the JustOneCX browser extension to play your draft on your own live page.
How do you point a step at a React element?
React class names are often generated and can change between builds. A tooltip can list more than one way to find its element, tried in order after the selector:
- Visible text, such as a button or link label.
- An ARIA role with an accessible name.
- A
data-jcxanchor. - A CSS selector.
Text and role targets keep working when generated class names change. A tooltip needs at least one of these. If you control the markup and want a stable hook, add a data-jcx anchor to the element and use it as the target.
The SDK scrolls the element to the middle of the screen before placing the tooltip. If the element is not rendered yet, 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 the tour finishes as finished with skips. React apps that load data before rendering a panel should raise the wait on that step.
Why does the tour not change when the route changes?
Most likely trackRouteChanges is off. A single-page app does not reload the page, so the SDK does not run again unless you ask it to. Pass trackRouteChanges: true to init(). Calling init() again is safe. A tour already on screen is not fetched and shown a second time.
If your router already calls init() itself, leave the option off.
What if nothing shows up?
Open the browser console. The SDK logs every problem with the prefix [JustOneCX]. Then check:
| Check | Fix |
|---|---|
| Is the tour Published? | Drafts are never sent. |
| Is the public key correct? | Copy it again from Settings, Developers. |
Is apiUrl set? |
Use https://api.justonecx.com. |
| Has the visitor seen it? | Finished or dismissed tours do not show again. Use a private window. |
| Is the element on the page? | Missing elements are skipped. Look for a console warning. |
The full list is in the troubleshooting guide. See also why a product tour is not showing.
What about server-side rendering?
Do not call init() on the server. It uses window and document. Calling it inside useEffect keeps it in the browser. Importing the package on the server is safe. If you use Next.js, read the Next.js product tour guide.
For setup details, see the frameworks page.
Frequently asked questions
Do I need the npm package?
No. You can paste the script tag before the closing body tag instead. With the npm package you call init() yourself, as shown above.
Where do I render the component?
Once, in your root component, so init() runs one time.
Does the same code work in Remix and Preact?
Yes. The docs use one example for React, Next.js, Remix and Preact.
Can a tour be replayed?
Yes. Turn on the persistent launcher in the tour's Settings tab, or call startTour from your own button.
See how it works in the live demo.