Troubleshooting

SDK Troubleshooting Reference

This reference guide provides solutions to common issues encountered during the installation and integration of the Userorbit SDK, helping you quickly diagnose and resolve problems.

SDK Not Loading

Problem: The Userorbit SDK script does not appear to be loading on your website.

Solutions:

  • Script Placement: Ensure the SDK initialization script is placed just before the closing </body> tag of your HTML, or added through your tag manager.
  • Content Security Policy (CSP): Check your website Content Security Policy. You may need to add https://cdn.userorbit.com to your script-src directive and https://api.userorbit.com to your connect-src directive.
  • Ad Blockers/Browser Extensions: Some aggressive ad blockers or privacy extensions might block the SDK. Test in an incognito window or with extensions disabled to rule this out.

Users Not Appearing in Contacts

Problem: After integrating the SDK, new users or their activities are not visible in the Userorbit Contacts section.

Solutions:

  • User identity not set: Ensure you are passing userId, email, or name in the init() config when the user is authenticated. User identity is set during initialization.
  • Incorrect Account ID: Double-check that the Account ID in your SDK initialization matches the one shown in Settings → Widget in your Userorbit Admin Panel.
  • SDK Not Initialized: Verify that the SDK has successfully initialized before attempting to call other methods. Check window.userorbit in the browser console.

Tours/Checklists Not Showing

Problem: Product tours, checklists, or other in-app experiences are not appearing for users even when they should.

Solutions:

  • Targeting Rules: Review the targeting rules for your tour or checklist within the Userorbit Admin Panel. Ensure the rules (URL, user segments, element visibility) match the current user state and page.
  • Register Route Changes: For SPAs, verify that registerRouteChange() is being called on navigation so page-targeted content can evaluate correctly.
  • Element Selectors: If your tour relies on specific CSS selectors, ensure those elements are present on the page and their selectors have not changed.
  • Tour/Survey/Checklist Published: Confirm the experience is published (not in draft) in the admin panel.

Console Errors

Problem: You are seeing errors related to Userorbit in your browser developer console.

Solutions:

  • Read the Error Message: Console errors often provide specific details. Look for messages indicating missing configuration, incorrect parameters, or network issues.
  • Network Tab: Check the network tab in your browser developer tools for failed requests to Userorbit domains (api.userorbit.com, cdn.userorbit.com).
  • Verify init() config: Ensure accountId is provided and is a valid string. The init() method expects an object: {accountId: "...", ...}.

Conflicts with Other Scripts

Problem: The Userorbit SDK appears to conflict with other JavaScript libraries or scripts on your page.

Solutions:

  • Namespace Collisions: The Userorbit SDK uses the global window.userorbit object. While unlikely to conflict, ensure no other script is overwriting this.
  • Asynchronous Loading: The SDK loads asynchronously to prevent blocking other scripts.
  • Error Isolation: Temporarily disable other scripts one by one to identify the specific conflicting script.

SPA Navigation Issues

Problem: In Single Page Applications (SPAs), Userorbit experiences like tours do not re-evaluate or appear correctly after client-side route changes.

Solution: Call userorbit.registerRouteChange() on every client-side route change. For React Router, use useLocation() or usePathname(). For Vue Router, watch the current route. For Angular, subscribe to NavigationEnd router events. The SDK does not automatically detect all SPA navigation patterns.

Performance Impact

Problem: Concerns about the SDK negatively affecting website load times or performance.

Solution: The Userorbit SDK is built with performance in mind. It loads asynchronously and has a minimal footprint. The initialization snippet uses a non-blocking pattern. If you observe performance issues, use browser developer tools to profile network requests and JavaScript execution to identify the bottleneck.

How to Verify SDK is Loaded

Open your browser developer console and type:

window.userorbit

If the SDK is loaded, this will return the Userorbit object. If it returns undefined, the SDK is not loaded.

Notes

  • Always ensure your SDK implementation uses the latest recommended snippet from your Userorbit project settings (Settings → Widget).
  • When contacting support, provide console logs, network requests, and details about your SDK initialization config.

Was this page helpful?