About Embedded Scripts

An embedded script is an app extension that injects an HTML code fragment into the DOM of a site. Unlike other extensions, embedded scripts aren't fully configured by default during app installation and an extra step is required to embed the code fragment. For detailed instructions, see:

Example use cases

Embedded scripts have a variety of uses, including:

  • Analytics: Use embedded scripts to listen to predefined Wix events as well as report and listen to custom events. Examples of predefined Wix events include clicking on a product or adding an item to a cart. For more information, see Analyze User Behavior Using Embedded Scripts.
  • Site Interaction: Access site data and integrate with apps made by Wix, such as Wix Stores and Wix Bookings, using the Site API. The Site API is only available for embedded scripts created with the CLI.
  • Customized Behavior: Enhance user engagement by adding dynamic features like pop-ups, sliders, or tooltips that react to user inputs.

Embedded script types

Script types determine whether site visitors consent to having your script run during their visit. Script types categorize embedded scripts for privacy and consent management purposes according to GDPR and similar data protection guidelines. For more information about meeting consent requirements and selecting a script type, see Implement Cookie Consent Requirements.

Each embedded script must specify 1 of the following types:

TypeDescriptionUse Cases
ESSENTIALCore functionality crucial to site operation.Authentication, security features
FUNCTIONALRemembers site visitors' choices to improve experience.Language preferences, UI customization
ANALYTICSProvides statistics on how visitors use the site.Google Analytics, Hotjar, Mixpanel
ADVERTISINGProvides visitor data for marketing purposes.Facebook Pixel, Google Ads, retargeting
Important:

If a script falls into multiple types, choose the option closest to the bottom of the list (most restrictive). For example, a script with both Analytics and Advertising aspects should use ADVERTISING.

Dynamic parameters

If you have custom keys or data per user, you can use dynamic parameters in your embedded script.

Dynamic parameters must:

  • Be strings.
  • Contain only alphanumeric characters (no special characters or spaces).
  • Be wrapped in double curly braces ({{).
  • Be enclosed in quotes (") to prevent code evaluation.
  • Be provided upon installation when calling Embed Script.

For example:

Copy

Important: If you add, remove, or change a dynamic parameter, users must update your app to receive the latest version of the embedded script.

Troubleshooting

The MISMATCHED ANONYMOUS DEFINE() MODULES... error is a common issue when working with AMD/UMD bundled scripts. The error occurs when an embedded script defines an anonymous module, either because it's bundled with AMD or it adds a script tag to the head containing an anonymous module.

To resolve the issue, try the following:

  • For the embedded script itself: If the script is bundled with AMD/UMD, make sure that you declare only named modules.
  • For scripts loaded by the embed:
    • If you own the code: If the scripts are bundled with AMD/UMD, make sure that you declare only named modules.
    • If you don't own the code: Check if requirejs exists on the window. If it does, load the script via requirejs instead of adding the script to the <head>. This approach is suboptimal and might still lead to race conditions and errors.

For more information on this issue, see RequireJS: Common Errors.

See also

Did this help?