Skip to main content
Usertour.js is silent in the browser console by default — it runs inside your production pages. When content does not show or a step does not attach, turn logging on to see what the SDK is doing: how the connection is going, which element it looked for, which attribute the server refused.

​
Turning logging on

Any of the three works. The first two need no code change. In the console. Open the browser’s developer tools and run:
Logging starts immediately and stays on for future page loads until you run usertour.setDebug(false). In the URL. Add ?usertour_debug=1 to the page’s address and reload. Logging is on for that page load only — useful when you want a screenshot from someone else’s browser without changing anything on their machine. The parameter must be in the query part, before any #, and the page you land on must keep it: a login redirect that rewrites the URL drops it. In code. Call usertour.setDebug(true) after usertour.init(). With the npm package (usertour.js 0.0.25 or newer) or an installation snippet copied from Settings → Installation after this release, the call is queued until the script has loaded, so it can sit anywhere. An older snippet does not know the method: calling it before the script has loaded throws and stops the rest of your script, so there, use the console or the URL instead.

​
Parameters

​
boolean
required
true opens the console log, false closes it and forgets the persisted setting.

​
Reading the output

Every line starts with [usertour-widget:<component>], followed by the message and the milliseconds since the previous line. The component tells you where to look: Levels follow the browser’s own: informational lines use console.log, degraded-but-continuing situations console.warn, failed operations console.error. Two messages are shown even when logging is off, because they mean Usertour will not work on the page and nothing else would tell you:
  • UI initialization failed — the stylesheet or the container could not be set up after several attempts, so no content can render. Check that js.usertour.io (or your self-hosted assets host) is reachable from the page.
  • Connection rejected by the server — the environment token or the identity token was refused, and the SDK has stopped reconnecting. Check the token passed to init(); with identity verification on, refresh the identity token and call identify() again.

​
By symptom

Nothing shows at all. Look for [usertour-widget:socket] lines. Connection connecting → connected followed by Connected means the network is fine. Only Connection idle → connecting and then Connection attempt failed (…) lines, never a Connected, means the server cannot be reached at all — the message in parentheses (websocket error, xhr poll error) is the browser’s reason, usually a proxy, a firewall or a blocking extension. A Connection … → reconnecting that never reaches Connected points at the network dropping later; Connection rejected by the server points at credentials. Once connected, content that still does not show did not match its start conditions for this user or page — check them in the builder, or ask the server with the API’s diagnose tools. A step does not attach. Look under flow for Step target element was not found on the page — the selector matched nothing for the configured number of seconds (setTargetMissingSeconds, else the theme’s setting, else 6 seconds), and the line says what happened next: the step was shown as a bubble or the flow was closed. Step target element stayed hidden past the timeout is the same for an element that exists but never became visible. Step has no target element configured means the step itself is missing a target in the builder. Launchers and banners log has no target element configured / has no container element configured the same way. Attributes are not updating. Look for Failed to send UpsertUser under socket — the write never reached the server — or, under core, Attribute "<name>" was not written: <reason>: the server refused that one value (it does not fit the attribute’s type, or the attribute is assigned by Usertour) and wrote the rest. The same reason comes back in the promise: const { rejected } = await usertour.updateUser(…). In the browser’s network panel, a healthy page has one wss:// connection to your Usertour server carrying client-message frames; a connection that keeps reopening is a rejection or a proxy closing idle sockets.

​
Notes

  • setDebug needs a server of this version or newer: on an older self-hosted server the SDK it serves does not have the method, in the console either.
  • Logging goes to the console only. Nothing is sent to Usertour.
  • The setting is per browser, stored under localStorage.debug next to other tools that use the same convention; usertour.setDebug(false) removes only Usertour’s entry.