Common widget implementation issues

When adding the Clym compliance widget to your website, most implementations are quick and seamless, but small setup missteps can prevent the widget from loading or behaving as expected. Common issues include pasting the code more than once, placing it outside of the <head> section, not copying the full embed script, or adding attributes like async or defer that interfere with proper initialization. In other cases, the script may not load correctly if it isn’t added as the very first script within the <head> tag. These small technical details can significantly impact performance and display, but they’re typically easy to identify and correct.

You may also notice differences in the widget’s appearance depending on geographic location, since compliance experiences can vary based on regional privacy regulations. Additionally, testing on a staging site without adding it as a registered subdomain in your Clym dashboard, attempting to use an embed code on a different domain than the one it was generated for, or failing to clear your browser cache after installation can all create confusion during setup. This guide outlines the most common implementation issues and provides clear, actionable steps to resolve them so your widget loads reliably and delivers the intended compliance experience.

Adding your code once

It is important that your Clym embed code is added to your website's source code only once to prevent possible conflicts, performance issues, or unpredictable behavior. When a script is duplicated, the browser attempts to initialize it each time it appears in the code. This can lead to:

Duplicate widgets or UI elements rendering on the page
Conflicting event listeners, which may cause buttons, banners, or modals to behave incorrectly
Race conditions, where multiple instances compete to load or modify the same data
JavaScript errors that prevent the widget from functioning properly
Slower page performance, since the browser must download and execute the same resource more than once

For the Clym compliance widget, duplicate script instances can also interfere with consent tracking, geolocation logic, and user preference storage. This may result in inaccurate consent records or inconsistent user experiences. Adding your Clym embed code only once supports stable performance, accurate functionality, and predictable behavior across your site.

Adding your code in the <head> section of your website

It’s important to add a script embed code to the <head> section of your website because that placement ensures the script loads early and predictably, before the page content is fully rendered. Clym's compliance widget needs to load as soon as possible to control or categorize other scripts on the page. If the code is placed in the <body> or lower in the document, it may load too late to manage tracking technologies, display banners at the correct time, or apply user preferences consistently. Additionally, the Clym script detects a visitor’s location to determine which regulatory experience to display, and block or allow certain cookies based on consent, all before other scripts execute. Placing the embed code as the first script within the <head> helps prevent conflicts, avoids race conditions, and ensures the widget can perform its compliance functions accurately and reliably across every page load.

Copy/paste the full code

It’s important to copy and paste your Clym embed code into your website’s <head> section in its entirety because each part of the script plays a specific role in loading and configuring the widget correctly. If any portion is removed, the script may fail to load, load incompletely, or behave unpredictably. Even small omissions can break functionality. A missing character, line, or attribute may prevent the widget from connecting to your account, retrieving the correct compliance configuration, detecting visitor location, or storing consent preferences properly. In some cases, a partial script may not trigger visible errors but will silently fail to perform key compliance tasks in the background. Copying and pasting the full code exactly as provided ensures accurate initialization, proper account association, and a consistent, fully functional compliance experience across your website.

Add any necessary subdomains

It’s important to add any staging or development websites to your Clym account as subdomains because the widget embed code is domain-specific and only authorized to run on whitelisted domains. When you generate your Clym embed code, it is tied to the primary domain listed in your account. If you attempt to install that same code on a staging site (for example, staging.yoursite.com or dev.yoursite.com) without adding it as a subdomain in your dashboard, the script will not be configured to work for that domain. This domain validation exists for security and compliance integrity. It prevents unauthorized use of your embed code on other websites and ensures that consent records, configurations, and regulatory experiences are correctly associated with the intended domain. By adding staging or development environments as approved subdomains, you allow the widget to load fully, connect to your account configuration, and function exactly as it would on your live site, giving you an accurate testing experience before going to production.

Add your Clym script as the first third-party script in your <head> section

It’s important to add the Clym script as the very first script in your website’s <head> section because it must initialize before any other third-party scripts load in order to properly manage them. If your website runs analytics tools, advertising pixels, chat widgets, or other tracking technologies, it is imperative that Clym properly allows or blocks these services, depending on user consent. If the Clym script loads after those tools, it may be too late to prevent them from setting cookies or collecting data before user consent has been obtained. By placing the Clym script at the top of the <head>, you ensure it runs first and can evaluate regulatory requirements (such as jurisdiction-specific rules) and user consent preferences before allowing or blocking additional scripts. This sequencing enables the widget to effectively control which technologies fire, delay scripts until consent is granted, and maintain accurate compliance records. Proper placement helps prevent accidental data collection prior to consent, reduces legal risk, and ensures your site behaves in alignment with your configured privacy settings.

Double-check your location

When testing your Clym widget, it’s important to understand that the user experience is location-based and driven by your configured jurisdiction and regulatory settings. The widget dynamically adjusts its appearance, language, consent requirements, and behavior depending on where a visitor is located and which regulations apply in that region. For example, a visitor in a jurisdiction with opt-in consent requirements may see a full consent banner before cookies load, while a visitor in another region may simply see an accessibility icon or a different initial notice. If you do not see the widget at all, or if it appears different from what you expect, the first step is to verify your current viewing location and confirm how that jurisdiction is configured in your jurisdiction settings. It’s possible that the region you’re testing from has different rules enabled, limited features, or even no banner configured. To accurately test alternate experiences, you can use the widget or Governance portal preview functionality available in the Clym Control Center, which allow you to simulate how the widget behaves for users from different locations. Understanding this dynamic behavior prevents confusion during testing and ensures you validate the correct compliance experience for each audience.

Ensure you are using your Clym embed code only for your domain

It’s important to use your Clym embed code only on the specific domain and approved subdomains associated with your account because the script is uniquely generated and tied to that domain configuration. Each embed code connects to a specific property profile within Clym, which contains that domain’s consent settings, jurisdiction rules, branding customizations, and compliance records. If you attempt to place the same embed code on a completely different domain, it will not initialize properly because that domain is not authorized (or “whitelisted”) within your account. This domain restriction facilitates both security and compliance accuracy. Consent records must be correctly associated with the exact website where user interactions occur, and regulatory settings may differ from one domain to another. If you manage multiple websites with different branding, audiences, or compliance requirements, each domain must be separately added and configured within Clym to generate its own unique embed code. This guarantees that the correct settings apply to each site and that consent tracking remains accurate and secure.

Clear your cache

It may be important to clear your browser cache during the testing or implementation process because browsers store previously loaded versions of scripts, stylesheets, and page content to improve performance. While caching speeds up normal browsing, it can interfere with implementation testing. especially after you’ve just added or modified your Clym widget embed code. If your browser is still serving a cached version of the page (or an older version of the script), you may not see the most recent changes reflected. Caching can also affect consent behavior. For example, if you’ve previously interacted with the widget, your browser may have stored consent preferences locally. This can prevent the widget notification from reappearing, making it seem like the widget isn’t loading correctly when it’s actually functioning as designed. Clearing your cache (and, in some cases, cookies or using an incognito/private window) ensures you’re viewing a fresh version of the site, loading the most up-to-date script, and testing the widget under clean conditions. This helps eliminate false errors and makes troubleshooting much more accurate.

Adding async/defer attributes

Adding async or defer attributes to your Clym script can cause problems because these attributes change how and when the browser executes the script. While async and defer are commonly used to improve page performance, they also alter the loading order and timing of JavaScript execution. For Clym's widget, execution timing is critical, especially when the script needs to run before other third-party technologies on the page. When async is added, the script downloads in parallel and executes as soon as it’s ready, regardless of document order. This can create race conditions where other scripts load and fire before the compliance logic initializes. When defer is used, the script waits until the HTML document has finished parsing before executing, which may be too late to block or conditionally allow tracking technologies based on user consent. In both cases, the widget may fail to properly manage cookies, delay scripts, or enforce jurisdiction-specific requirements. For this reason, the embed code should be added exactly as provided, without modifying it with additional attributes. so it loads and executes in the precise order required for reliable compliance behavior.

If you encounter any challenges, please reach out to support@clym.io

Updated on: 04/03/2026

Was this article helpful?

Thank you!