Skip to main content

Guide to Debugging Issues with AI Widget Integration

Learn how to troubleshoot common UserWay AI Widget installation, loading, plugin, cache, network, and browser issues quickly.

This guide helps experienced users, web administrators, developers, and technical analysts diagnose and resolve UserWay AI Widget installation, loading, and display issues.

ℹ️ Note: Most troubleshooting steps require access to your browser's Developer Tools (F12 on Windows/Linux or Cmd + Option + I on macOS).

Embed Code and Account Verification

Before reviewing browser errors, verify that the widget script is correctly deployed on the page.

  1. View the live page source (Ctrl + U or Cmd + Option + U).

  2. Search for cdn.userway.org/widget.js.

  3. Verify that the data-account attribute exists on the <script> tag and contains your valid UserWay Account ID.

Example:

  1. Confirm the account ID has not been replaced by placeholder text such as ACCOUNT_ID_HERE or removed by an HTML minifier or optimization tool.

  2. Log in to the UserWay Dashboard and confirm the active domain, including any subdomains, staging environments, or production environments such as www.example.com, is registered under your account.

  3. Verify that the script is embedded in the live website, either inside the <head> element or before the closing </body> tag, and not only within an unpublished CMS draft or preview environment.

ℹ️ Note: If an Account ID Mismatch error appears in the UserWay Dashboard, verify that the account ID embedded on the website matches the account currently open in the dashboard: Account ID Mismatch Warning Displayed in the UserWay Dashboard

Console Errors

Console errors often provide the fastest indication of script failures, blocked resources, or third-party conflicts.

  1. Open Developer Tools and click the Console tab.

  2. Search or filter for:

    • userway

    • widget.js

    • cdn.userway.org

    • api.userway.org

  3. Review any reported errors.

Common error types include: (Resolve any reported errors and refresh the page.)

  • CORS / Network Blocked: Indicates a firewall, security policy, or CDN restriction.

  • CSP Violations: Indicates the website's Content Security Policy is blocking scripts, styles, or API requests.

  • Uncaught SyntaxError / TypeError: May indicate a conflict with another JavaScript resource on the page.

Content Security Policy (CSP) Restrictions

A restrictive Content Security Policy may prevent the widget, stylesheets, or configuration services from loading correctly.

  1. Open Developer Tools and click the Console tab.

  2. Look for CSP violation messages referencing UserWay resources:

  3. Verify that your CSP configuration allow wildcard domain *.userway.org

  4. Save and deploy your CSP updates.

  5. Reload the page and verify that CSP errors no longer appear.

ℹ️ Note: Review the official UserWay CSP documentation for the latest domain and directive requirements.

Cache, Local Storage, and Widget State

Browser storage or cached content can prevent recent configuration changes from appearing.

  1. Open the website in a private or incognito browser window with all extensions disabled.

  2. Open Developer Tools and navigate to Application (or Storage) > Local Storage.

  3. Clear local storage data or review keys beginning with userway- or uw-.

  4. Clear any applicable server-side, CMS, and CDN caches.

Common examples include:

  • WP Rocket

  • LiteSpeed Cache

  • W3 Total Cache

  • Cloudflare

  • Fastly

💡 Tip: (Use Intercom callout: green) After clearing caches or updating your widget configuration, perform a hard refresh to ensure your browser loads the latest version of the page instead of using cached files. Use Ctrl + F5 on Windows/Linux or Cmd + Shift + R on macOS.

Security Systems and Firewall/CDN Blocking

Security products and Web Application Firewalls (WAFs) may block UserWay resources.

  1. Verify whether services such as Cloudflare, Akamai, Sucuri, AWS WAF, or Imperva are active.

  2. Review firewall and WAF logs for blocked requests to:

    • cdn.userway.org

    • api.userway.org

  3. If using Cloudflare, temporarily disable Rocket Loader or script optimization features that may change widget loading behavior.

  4. Allowlist UserWay hostnames if filtering or blocking is detected.

⚠️ Important: Firewall and CDN rule updates may require additional propagation time across edge servers (Contact your server administrator/support)

Plugin, CMS, and Script Minification Conflicts

Optimization tools can alter script execution order and prevent the widget from loading properly.

Platform Plugin Verification

  1. Verify that your UserWay plugin or app is updated to the latest supported release.

  2. If using WordPress, review optimization tools such as Autoptimize or WP Rocket.

  3. Add cdn.userway.org to any script exclusion or optimization bypass lists.

Plugin Conflict Testing

  1. Temporarily disable caching, minification, or accessibility-related plugins.

  2. Refresh the website after each change.

  3. Identify whether a specific plugin prevents the widget from loading correctly.

Manual Installation Fallback

  1. Disable the platform plugin if it is determined to be the source of the issue.

  2. Embed the UserWay script directly within the site's <head> section or deploy it through Google Tag Manager.

⚠️ Important: Always create a website and database backup before modifying or disabling plugins in a production environment.

CSS and Display Conflicts

In some cases, the widget loads successfully but remains hidden because of custom CSS or display settings.

Verify Widget Configuration

  1. Review your UserWay Widget settings.

  2. Confirm the widget is not configured as:

    • Headless

    • Custom Trigger

  3. Verify that Hide on Mobile and Hide on Desktop settings are not enabled unintentionally.

💡 Tip: If you're unsure whether the UserWay widget is failing to load or is simply hidden, view the page source by pressing Ctrl + U (Windows/Linux) or Cmd + Option + U (macOS). Then search for cdn.userway.org/widget.js. If the script is present in the page source, the widget code is loading on the page and the issue may be related to CSS, widget settings, browser storage, or other display conflicts rather than the installation itself.

Inspect Widget Elements

  1. Open Developer Tools and click the Elements tab.

  2. Search for:

    • #userwayAccessibilityIcon

    • div[data-userway-widget]

  3. If the element exists but is not visible, review computed styles for:

display: none !important;
visibility: hidden;
opacity: 0;

Also verify:

  • Negative z-index values

  • Overlapping headers, modals, or chat widgets

  • Parent containers using overflow: hidden

Adjust CSS Overrides

  • Add targeted CSS adjustments as needed to resolve stacking, positioning, or visibility conflicts.

Network and Connection Diagnostics

Verify that all required resources load successfully.

  1. Open Developer Tools and click the Network tab.

  2. Filter requests by userway.

  3. Reload the page.

  4. Verify successful responses for:

    • widget.js from cdn.userway.org

    • Configuration and tuning requests from api.userway.org

  5. Review all failed requests.

Common status codes include:

  • 403 Forbidden

  • 404 Not Found

  • 500 Server Error

  • (failed)

  • net::ERR_BLOCKED_BY_CLIENT

net::ERR_BLOCKED_BY_CLIENT typically indicates that a browser extension, ad blocker, or privacy tool blocked the request.

Browser Extensions and Cross-Browser Validation

If the widget appears in one environment but not another:

  1. Test the website in Chrome, Firefox, Safari, and Edge.

  2. Disable browser extensions such as:

    • uBlock Origin

    • AdBlock Plus

    • Ghostery

    • Brave Shields

  3. Test again using a clean browser profile or an incognito window.

  4. Verify that the browser version meets modern web standards and supports current JavaScript functionality.

Expected Result

The UserWay AI Widget initializes successfully, all required CDN resources and configuration APIs return HTTP 200 responses, no CSP or JavaScript errors appear in the browser console, and the accessibility launcher icon displays correctly on the page.

Need More Help?

Contact the UserWay Support Team — we're here to assist you.

Get in touch with UserWay Support.

Related Articles
Did this answer your question?