Use the first failing step to narrow an SDK problem: loading the script, initializing the workspace, identifying the person, receiving an event, or displaying an experience.

Start with a dedicated test account and a page where you can reproduce the problem. Record the expected behavior and the action that actually occurs.

The SDK does not load

Check the browser Network panel for the first failed Userorbit request.

  • For a script installation, use the current snippet from your workspace and confirm that window.userorbit exists after the script loads.
  • For userorbit-js, the package loads the browser runtime. Check both the package integration and the runtime script request.
  • Check that your Content Security Policy permits the actual script and API destinations used by the installation. A successful script request does not prove that API requests are permitted.
  • Test whether a browser extension, tracking protection, network filter, or a custom host is blocking the request.

Use the configured URLs visible in Network when investigating. Do not broaden a production CSP to allow every destination just to remove an error.

Initialization fails or runs twice

Call init() from browser code once, with the intended workspace's public Account ID. Keep it out of server-only rendering code and avoid installing both a tag-manager snippet and another application integration.

In React and Next.js, check whether multiple layouts or component effects mount the integration. Development Strict Mode can expose repeated initialization paths. Test the production build separately before attributing all duplication to the SDK.

Calls after initialization do not make init() a general configuration-update method. Use the appropriate identity or display method when changing those values.

Inspect the console and Network panel even when an awaited call returns. SDK initialization and queue completion are not guarantees that data was received successfully.

For the Chrome localhost-specific problem, see Fix Userorbit initialization errors on localhost in Chrome.

A contact is missing or has the wrong identity

Sequence identify() after initialization and after your application's authentication is ready. Confirm the application user ID and the Userorbit workspace, then search Contacts by the test person's ID or email.

Pass a stable ID explicitly. A new initialization without a user ID can reuse a saved browser identity. Check active tenant attributes after a tenant switch, and remember that omitting an old attribute does not remove it.

logout() clears configuration but does not erase the stored distinct ID or guarantee that an active replay stops. reset() reinitializes with the existing identity. Test sign-out and a second person's sign-in rather than assuming either method creates an unlinked visitor.

See User identity API reference.

A code event is missing

  1. Open Events in the workspace used by the SDK.
  2. Confirm that the event exists with type Code.
  3. Compare its Key with the exact string passed to track(). An unknown key produces an invalid_code error.
  4. Check that the call runs after the intended product action succeeds.
  5. Check analytics configuration and the first failed API request.
  6. Open the correct project in Analytics → Live Events and remove filters that could hide the test event.

If Live Events receives the event but a report does not show it, review the report's selected event, date range, filters, and project before changing the SDK.

An action or page view appears twice

Look for two handlers calling the same event, a repeated component effect, duplicate installation, or both automatic and manual route detection.

The SDK observes common History API, popstate, and hash navigation. Check Live Events before adding registerRouteChange(). Use it only as a fallback for a navigation that is actually missing. Remove that fallback if automatic detection and the manual hook both produce the same page view.

Test a full page load and a client-side route change separately. Compare the event key, timestamp, and identity, rather than relying only on a chart total.

An experience does not appear

Confirm that the tour, checklist, survey, or announcement is published in the same workspace as the installation. Then check its URL rules, audience, required page elements, schedule, and frequency. Prior completion or dismissal can make an otherwise eligible test behave differently.

Use a fresh dedicated test profile or the product's available testing controls. Do not remove production targeting or privacy settings merely to force a test display.

Send useful support evidence

Include the framework and browser versions, installation method, package version if applicable, expected event key or experience ID, approximate test time with time zone, and the status of the first failed request.

Share a redacted URL pattern and redacted initialization options. Remove credentials, identity fields, query-string values, customer content, and request bodies containing personal data from screenshots or logs.

If you use a custom SDK errorHandler, record only the diagnostic fields needed for the investigation. Do not forward whole error objects into another service without checking their contents.

Was this helpful?