Who can use this document?
Although anyone could understand and work through this guide, the reading is recommended for experienced users, such as Developers or Analysts.
How do I use this document?
This article was written to help you find the root cause of any installation issues, and potentially solve within your structure. You can also send any findings to UserWay's Support mailbox, our Support Team is aimed at solving most of the bugs or issues that arrive.
Console Errors: Troubleshoot missing files, JavaScript errors, and CORS issues. One of the first places to check when troubleshooting an AI widget is the browser console. Common console errors related to AI widgets can include missing files, JavaScript errors, or CORS (Cross-Origin Resource Sharing) issues.
How to Debug Console Errors:
Access Developer Tools: Open the browser's developer tools (usually by pressing F12 or Cmd + Option + I), navigate to the Console tab, and check for errors.
Check for errors related to these keywords: userway; remediation; widget.js: Ensure that all files are being loaded correctly and no errors are present in the console
The fix is simple, you need to whitelist our CDNs in your Hosting Platform. More details can be found on the article below:
Plugin Issues (Shopify, WordPress, etc.): Fix compatibility issues, outdated plugins, or plugin conflicts. When adding the AI Widget to platforms like Shopify or WordPress, plugins play a crucial role. Plugin-related issues can stem from incorrect configurations, outdated versions, or conflicts with other installed plugins.
How to Debug Plugin Issues:
Check Compatibility: Ensure the AI widget plugin is compatible with the version of your platform (Shopify, WordPress, etc.).
Update Plugins: Outdated plugins often cause conflicts, so make sure you’re using the latest version.
Conflict with Other Plugins: Try deactivating other plugins to see if the AI widget starts functioning correctly. If it does, there may be a conflict with another plugin.
If you still face issues with the plugin, you may want to try manual installation instead of plugin installation.
Related articles:
-Manual installation guide for Shopify-Manual installation guide for WordPress
Cache Issues: Ensure your cache isn’t serving outdated content. Caching can be a double-edged sword. While it improves performance, it can also serve outdated content, preventing changes to your site's code, therefore, the AI widget from reflecting instantly after the installation.
How to Debug Cache Issues:
Clear Browser Cache: Before concluding that there is an issue with the widget itself, clear your browser's cache to ensure you’re seeing the most recent version.
Purge Server Cache: If your website uses server-side caching (e.g., through CDNs like Cloudflare), purge or disable the cache temporarily to troubleshoot.
Disable Plugin Caching: Many CMS platforms come with caching plugins. Force the cache to be cleared, usually through the plugin admin UI. If it doesn't work, as a last resort, temporarily disable the cache plugin, so it will help us determine whether the cache is interfering with your AI widget.
Network Issues: API or Connection Problems: Resolve API key or connection errors. Your AI Widget depends on an external CDN connection to work correctly, meaning you need an internet connection for the Widget to work. Errors in network connection can manifest as widgets not loading, errors in the console, or a lack of responsiveness.
How to Debug Connection Issues:
Network Inspection: Use the Network tab in your browser's developer tools to inspect whether calls are being blocked or delayed.
Access our CDN from your browser: check if the CDN is responsive and your connecting is stable.
Try to type a new site in your browser, and see if it loads correctly
Reset your Wi-Fi Router and run another test within 5-8 minutes
CSS Styling Conflicts: Fix design conflicts between widget styles and your website’s CSS. The AI Widget works to fix several accessibility styling issues, such as contrast, font sizes, weight, and much more to make your site comply with contrast rules. Sometimes, these styles that may conflict with your website’s existing CSS, causing display issues.
How to Debug CSS Conflicts:
Inspect Element: Use your browser’s developer tools to inspect the elements of of your site and look for any conflicting styles.
Override CSS: If necessary, add custom CSS to override the widget’s default styling, ensuring it blends with your site design, make sure to use the !important rule.
Ignore Widget remediation by adding specific attributes: check more on this guide if you need to bypass some of the Widget remediation for some reason.
Widget Not Displaying After Installation: Address script or installation issues. In this case, the widget simply does not appear on the page. This could be due to script loading issues, incomplete installation, or JavaScript conflicts.
How to Debug Loading Issues:
Check Script Placement: Ensure the AI Widget’s script is placed correctly in your site’s HTML, preferably before the closing </head> tag.
Verify Installation Steps: Double-check all installation instructions for your platform provider. See all installation guides here.
Check JavaScript Conflicts: Ensure other scripts on your website are not interfering with the AI widget.
Cross-Browser Compatibility: Ensure your widget works across different browsers. Your AI Widget is made to work consistently across all browsers. If you find that the Widget is working perfectly on one browser but fail to load or display correctly on another, that could be caused by Cross-browser issues. These kind of issues are particularly common in older versions of Internet Explorer or niche browsers.
How to Debug Cross-Browser Issues:
Test on Multiple Browsers: Ensure that the widget works on all major browsers (Chrome, Firefox, Safari, Edge).
Use Browser-Specific Fixes: If necessary, apply browser-specific CSS or JavaScript fixes.
Check JavaScript Features: Some older browsers may not support modern JavaScript features used by the AI widget.
When the Widget fails to function as expected, debugging can be a multi-step process that involves inspecting the console, checking plugins, clearing caches, and ensuring compatibility. The articles linked in each section provide deeper dives into these specific issues, making this guide a one-stop resource for resolving AI widget integration problems.
If you still face issues, always remember: we are here 24x7 - please connect with our Support Team at desk@support.userway.org