This article serves as a comprehensive troubleshooting guide for common scenarios where product tours created with the Userorbit Admin Panel may not be displaying as expected to your users. It covers diagnosis steps and solutions for each potential issue.
Common Issues and Their Solutions
- SDK not installed or initialized —
Installation Issue— If the Userorbit SDK is not correctly installed or initialized on your website or application, tours will not load.- Diagnosis: Open your browser's developer console (F12) and check for any errors related to "Userorbit" or "SDK initialization." Verify that the Userorbit SDK snippet is present in your application's HTML, preferably within the
<head>tag or just before the closing</body>tag. - Solution: Ensure the Userorbit SDK installation snippet is correctly embedded in your application. Refer to the Userorbit documentation for the most up-to-date installation instructions.
- Diagnosis: Open your browser's developer console (F12) and check for any errors related to "Userorbit" or "SDK initialization." Verify that the Userorbit SDK snippet is present in your application's HTML, preferably within the
- Tour is in draft (not published) —
Tour Status— Tours must be published in the Userorbit Admin Panel to be visible to users.- Diagnosis: Navigate to the "Product Tours" section in your Userorbit Admin Panel and check the status of the tour. If it shows "Draft" or "Unpublished," it will not appear for users.
- Solution: Edit the tour in the Admin Panel and click the "Publish" button to make it live.
- User doesn't match targeting rules —
Targeting Mismatch— If the user's attributes or segments do not align with the tour's configured targeting rules, the tour will not be displayed.- Diagnosis: In the Userorbit Admin Panel, review the "Targeting" section of your tour. Compare the configured rules (e.g., user properties, segments, device type) with the actual attributes of the user experiencing the issue. Use Userorbit's user lookup feature to inspect individual user data.
- Solution: Adjust the tour's targeting rules to accurately reflect the desired audience, or ensure the user's attributes match the existing rules.
- User already completed/dismissed the tour —
User History— By default, tours are designed to be completed or dismissed once per user.- Diagnosis: Check the user's activity history within the Userorbit Admin Panel to see if they have previously completed or dismissed the specific tour.
- Solution: For testing purposes, you can often reset a user's tour history in the Admin Panel. For live scenarios, understand that the tour will not reappear for users who have already interacted with it, unless the tour's settings allow for repeat displays.
- Target element not found on the page (CSS selector changed) —
UI Changes— If a tour step is configured to highlight or attach to a specific UI element (using a CSS selector) and that element's selector has changed due to a UI update, the tour step may fail.- Diagnosis: Open the problematic page in your browser, use the developer tools "Inspector" to examine the target UI element. Compare its current CSS selector with the one configured in the tour step within the Userorbit Admin Panel. Look for console errors indicating a missing element.
- Solution: Update the CSS selector for the affected tour step(s) in the Userorbit Admin Panel to match the current structure of your application's UI.
- URL targeting mismatch —
URL Configuration— Tours can be configured to only appear on specific URLs or URL patterns. A mismatch will prevent the tour from loading.- Diagnosis: Verify the exact URL where the tour is expected to appear. Then, check the "URL Targeting" settings for the tour in the Userorbit Admin Panel (e.g., "Exact match," "Starts with," "Contains").
- Solution: Adjust the tour's URL targeting rules to precisely match the intended page(s) where the tour should be displayed.
- Tour scheduled for future date —
Scheduling— Tours can be scheduled to start and end on specific dates and times.- Diagnosis: In the Userorbit Admin Panel, review the "Schedule" settings for the tour. Ensure the current date and time fall within the tour's active period.
- Solution: Modify the tour's start date and time in the Admin Panel to activate it immediately or at the desired future time.
- JavaScript errors blocking tour —
Application Conflicts— Other JavaScript errors on your page can sometimes prevent the Userorbit SDK from executing correctly.- Diagnosis: Open your browser's developer console (F12) and look for any red error messages that are unrelated to Userorbit but occur before or concurrently with the expected tour load.
- Solution: Debug and resolve any existing JavaScript errors within your application. A healthy application environment is crucial for third-party SDKs to function properly.
- Ad blockers or CSP blocking the SDK —
Network/Security— Browser extensions like ad blockers or strict Content Security Policies (CSP) can prevent the Userorbit SDK from loading or communicating with its servers.- Diagnosis: Temporarily disable ad blocker extensions in your browser. In the developer console's "Network" tab, look for blocked requests to Userorbit domains. Check the console for "Content Security Policy" errors.
- Solution: Advise users to disable conflicting browser extensions. If a CSP is in place, ensure that Userorbit domains (e.g.,
*.userorbit.com) are whitelisted for scripts, styles, and other necessary resources.
- Tour display frequency limit reached —
Frequency Settings— Tours can have frequency caps (e.g., "show once every 7 days") to avoid overwhelming users.- Diagnosis: Review the "Frequency" or "Display Settings" for the tour in the Userorbit Admin Panel. Check the user's history to see if they have recently been shown the tour and are within a cooldown period.
- Solution: Adjust the tour's frequency settings if you wish it to appear more often, or wait for the configured cooldown period to expire.
Notes
- Always clear your browser cache and cookies when testing tour display issues, as cached data can sometimes interfere.
- Ensure your network connection is stable and not blocking any necessary domains.
- If you've exhausted these troubleshooting steps, gather relevant screenshots, console logs, and tour configuration details, then contact Userorbit Support for further assistance.