The UserWay Accessibility Widget can be installed on most websites in just a few minutes.

You can get started by generating or retrieving your UserWay installation code. If you have access to manage your website and add JavaScript, you can install the widget yourself.

If someone else manages your website or you are not comfortable making technical changes, simply share the installation code with your developer, IT team, agency, website administrator, or the person responsible for maintaining your website.

This guide explains how to:

Generate or retrieve your UserWay widget installation code
Identify who can install the widget for you
Install the widget on your website
Find platform-specific installation guides
Verify that the installation is working correctly
Find troubleshooting resources if something does not work as expected

⚠️ Important: Generate the installation code using the UserWay account that manages the website and its active subscription. Using code from another account can load the wrong configuration, show the Free widget, and prevent Dashboard changes from syncing.

Generate or Retrieve Your UserWay Widget Installation Code

You can get your widget installation code in two ways.

Option 1: Generate the Code

Go to https://userway.org/code/.
Enter the email address associated with the UserWay account that manages the website.
Follow the instructions to generate your widget installation code.
Copy the installation code or save the generated installation URL.

Option 2: Retrieve the Code from the UserWay Dashboard

If you're already logged in to the UserWay Dashboard:

Go to https://manage.userway.org/.
From the left-side menu, open Embed Code.
Copy the widget installation code shown there.

💡 Tip: If someone else will install the widget, share the generated installation URL when possible to avoid copy-and-paste errors.

Who Should Install the Widget?

If you manage your website and have access to add JavaScript or third-party scripts, you may be able to install the widget yourself.

If you don't have this access or aren't comfortable making changes to your website, send the installation information to the person or team responsible for maintaining it.

This could be your:

Web developer
Web designer
Webmaster
Website administrator or manager
IT team
Web or marketing agency
Website provider
Hosting provider
Freelancer
Technical consultant

💡 Tip: Not sure who to contact? Start with the person or company that built or currently maintains your website.

What Should I Send to My Developer or Website Administrator?

You don't need to understand or explain the technical installation process yourself.

Provide the person managing your website with:

Your website URL eg; example.com
Your installation code or the code generated.
A request to install the UserWay JavaScript on your website
A request to place the code within the website's <head> section whenever possible

You can send them a request similar to:

Please install the UserWay Accessibility Widget on our website.
Website: https://example.com
UserWay installation: https://userway.org/code/xxxxx
Please add the UserWay installation script to the website's <head> section whenever possible and publish it across the website.

Install the UserWay Widget on Your Website

Once you have generated or retrieved the correct installation code:

Open your website's CMS, website builder, source code, or tag management platform.
Locate the area where third-party JavaScript or custom scripts can be added.
Add the UserWay installation code using the installation method supported by your platform.
Whenever possible, place the UserWay installation code within the website's <head> section.
Save and publish your changes.
Visit your website and confirm that the UserWay Accessibility Widget appears.

ℹ️ Note: Installation methods vary by platform. Some use custom code, plugins, GTM, theme editing, or developer access.

Installation Methods Vary by Platform

The exact installation method depends on the website platform, CMS, website builder, or development environment being used.

If a dedicated UserWay installation guide is available for your platform, follow that guide for the recommended installation method.

WordPress: Installing the UserWay Widget WordPress Plugin

Shopify: Installing the UserWay Widget on Your Shopify Website

Joomla: UserWay Widget: Joomla Installation Guide

Odoo CMS: How to Install the Widget on Odoo CMS

Google Tag Manager (GTM): UserWay Widget: Google Tag Manager Installation Guide

ℹ️ Note: If your platform does not have a dedicated UserWay installation guide, use the platform’s supported method for adding third-party JavaScript, preferably within the <head> section. If you’re unsure how to do this, contact your platform or CMS provider for further assistance.

Verify the UserWay Widget Installation

After publishing the installation:

Open your website in a new browser tab.
Allow the page to fully load.
Confirm that the UserWay Accessibility Widget icon appears.
Open the widget and confirm that the accessibility menu and features are available.
If you have an active Pro subscription, confirm that Pro features such as Screen Reader are displayed.
If you've customized the widget through the UserWay Dashboard, verify that those changes are reflected on the website.

ℹ️ Note: Caching, CDNs, and security or optimization tools may delay changes. Allow up to 24 hours for the Dashboard to re-scan and validate the installation.

Verify the UserWay Account ID

If the widget appears but does not match the configuration shown in your Dashboard, verify that the correct UserWay Account ID is installed.

Locate the UserWay widget code on the website and check the data-account value.

The installed Account ID should match the UserWay account currently managing the website.

An Account ID Mismatch warning means the Dashboard has detected that the website is using widget code associated with a different UserWay account.

This can result in:

The wrong widget configuration being displayed
Dashboard settings not synchronizing with the widget
Pro features not appearing

The Free version being displayed if the installed Account ID belongs to an account without an active Pro subscription

For Account ID Mismatch troubleshooting and configuration guidance, see ID Mismatch Warning Displayed in the UserWay Dashboard

Content Security Policy (CSP)

If your website uses a Content Security Policy (CSP), required UserWay resources must be allowed for the widget and its features to load correctly.

Relevant CSP directives may include:

script-src style-src img-src connect-src font-src media-src frame-src

For CSP-specific troubleshooting and configuration guidance, see:

Content Security Policy Directive: frame-src 'self' Error

⚠️ Important: CSP restrictions can prevent the widget or individual features from loading correctly.

Widget Does Not Load or Work as Expected

If the widget does not appear or you are experiencing an integration issue, see:

Guide to Debugging Issues with AI Widget Integration

Widget Is Installed but Pro Features Are Missing

If the widget appears but displays the Free version, Pro features are missing, or Dashboard settings are not reflected on the website, see:

Troubleshooting: The Widget on Your Website Is Not the Pro Version After Installation

Cloudflare or DOMPurify

If UserWay resources appear to load but the widget itself does not appear, and your website uses Cloudflare or DOMPurify, see:

UserWay Widget Does Not Load Due to Cloudflare DOMPurify

Quick Installation Checklist

Before considering the installation complete, confirm:

The widget is visible on the live website.
The correct UserWay Account ID is installed.
The widget opens and its accessibility features are available.
Pro features are displayed if the website has an active Pro subscription.
Dashboard customizations are reflected on the website.
The installation has been published across the pages where the widget should appear.

✅ Installation verified: The widget appears, opens correctly, shows the expected features, and reflects the settings from the correct UserWay account.