If a product tour is not showing, check six things in order: the tour is published, the public key is correct, apiUrl is set, your targeting matches you, you have not already seen it, and the step's element is on the page. Then open the browser console and look for messages that start with [JustOneCX]. The SDK logs every problem with that prefix.
Where should you start?
Open your browser's developer console first. The SDK logs every problem with the prefix [JustOneCX]. Filter the console by that text. A warning there often names the cause in one line.
Then work through the checklist below. It follows the order from the most common cause to the least common.
| Check | Fix |
|---|---|
| Is the content Published? | Drafts are never sent to visitors. |
| Is the public key correct? | Copy it again from Settings → Developers. A rotated key stops the old one working at once. |
Is apiUrl set? |
Use https://api.justonecx.com. Without it the SDK calls localhost:8000. |
| Does targeting match you? | Test with Everyone targeting first. |
| Has the visitor already seen it? | Finished or dismissed content is not shown again. Clear localStorage for the site, or use a private window. |
| Is the step's element on the page? | Missing elements are skipped. Look for a console warning. |
Is the tour published?
Drafts are never sent to visitors. Saving a tour does not make it live. Open the tour and check that its status is published. If you built the tour with an AI assistant, remember that everything it creates is a draft until a person publishes it. See the AI assistant article.
You can also preview a draft. A preview link plays the tour's current draft for 24 hours on any page where the SDK runs. This helps you tell a content problem from a targeting problem.
Are the public key and apiUrl right?
Copy the public key again from Settings → Developers. If the key was regenerated, the old key stops working at once.
Check apiUrl. Without it the SDK calls localhost:8000, and the SDK logs a warning. A correct setup looks like this:
import { init } from "@justonecx/sdk";
await init({
publicKey: "pk_your_workspace_key",
apiUrl: "https://api.justonecx.com",
trackRouteChanges: true,
});
Also check that init() ran at all. If your key comes from a NEXT_PUBLIC_* or VITE_* variable, it is read at build time. An empty key means the SDK is skipped. Rebuild after setting the variable, and make sure your CI build sets it too.
Does your targeting match you?
Tours use targeting. The audience is decided on the server before content is sent. Page rules are checked in the browser. To test, set the tour's targeting to Everyone first. If the tour then shows, the problem is the audience or the page rule.
If targeting depends on traits, the traits must be saved before targeting can match them. Use await identify(...), then call init() again. See identify users with the SDK.
Has the visitor already seen it?
Finished or dismissed content is not shown again. If you have been testing the tour, you may have finished it. Clear localStorage for the site, or open a private window.
Is the element on the page?
A tour step points at an element. If the element is missing, the step is skipped, and the SDK logs a console warning. Check that the selector still matches after your last release. A renamed class is a common cause. For multi-page tours, check that the page rule matches the page where the element lives.
Is it a CORS or Content Security Policy problem?
If the console shows a red request with status 403 or a CORS error, the origin is not allowed. Add your site's origin to Settings → Developers → Domains & CORS. Include http://localhost:<port> for local work. Allowed origins are CORS only. They are not authentication. See the allowed origins guide.
Other signs and fixes:
- A
401request means the public key is wrong or was rotated. Copy it again. Refused to connect to 'https://api.justonecx.com/...'with aconnect-srcmessage means your site's CSP blocks the SDK. Addhttps://api.justonecx.comandwss://api.justonecx.comtoconnect-src, reload the server that sets the header, then hard-refresh.[JustOneCX] The browser could not reach ...means the request never got an answer. Causes are CSP, an ad blocker, being offline or a wrongapiUrl. Try a private window with extensions off.
Does the tour stay the same when the page changes?
If your app is a single-page app, tours do not change when the route changes. Pass trackRouteChanges: true to init(), or add data-track-route-changes="true" on the script tag.
Are there other console messages to know?
identify() called before init(): runinit()first. In a framework, callinit()in your top-level component andidentify()in an effect that runs after it.- Errors during server-side rendering: you called
init()on the server. Move it intouseEffect,onMount, a.clientplugin or anisPlatformBrowsercheck. identify() was rejected: identity verification is on and no validuserHashwas sent.
The full list is on the troubleshooting page. If you are still stuck, contact the JustOneCX team from your dashboard and include the console output and your SDK version.
Frequently asked questions
Why does my tour show in a private window but not in my normal browser?
You have probably finished or dismissed it. Finished or dismissed content is not shown again. Clear localStorage for the site.
What do I do if there is no console message at all?
init() may never have run. A NEXT_PUBLIC_* or VITE_* key is read at build time, so an empty key means the SDK is skipped. Rebuild after setting the variable.
Do I need to add my site to allowed origins?
Yes, if the console shows a 403 or a CORS error. Add the origin under Domains & CORS, and include http://localhost:<port> for local work.
Can I replay a tour I already finished?
Yes. startTour("export-flow") plays a tour immediately, using its key or id. It ignores targeting, frequency cap and completion state. Only published tours start.
See how it works in the live demo.