Embedded Scripts

An embedded script is an HTML code fragment injected into the DOM of a Wix site. Unlike other site extensions, it isn't placed by the Wix user in the editor. Once embedded, the script runs on the live site.

When to use an embedded script

Use an embedded script when you need to inject a raw HTML or JavaScript fragment into the site rather than a placeable component. Common cases include:

• Adding analytics or tracking pixels, like Google Analytics, Facebook Pixel, or a retargeting tag.
• Listening to Wix events and reporting them to an external system, like sending Add to Cart events to a customer-data platform, or defining custom events for behaviors Wix doesn't track out of the box.
• Adding lightweight overlay UI, like a pop-up, banner, or tooltip anchored to the page edge.

Embed a script

Unlike other site extensions, embedded scripts aren't fully configured when an app is installed. The app developer needs to provide an explicit step that injects the script onto the site, by calling the Embed Script API. The call can come from the app's backend, or from a dashboard page where the Wix user triggers it manually.

Script types and consent

Each embedded script declares a script type that determines how it interacts with the site's cookie consent UI. The platform supports the following types, ordered from least to most restrictive:

• ESSENTIAL: Core functionality the site can't work without, like authentication or security primitives. No consent required.
• FUNCTIONAL: Remembers visitor choices to improve the experience, like language or UI preferences. Consent required.
• ANALYTICS: Reports usage data, like Google Analytics, Hotjar, or Mixpanel. Consent required.
• ADVERTISING: Provides visitor data for marketing, like Facebook Pixel, Google Ads, or retargeting. Consent required.

If a script falls into multiple types, use the most restrictive applicable type. For example, a script used for analytics and advertising should be declared as ADVERTISING.

Dynamic parameters

A script can accept dynamic parameters that get filled in per installation, so the same script can carry per-app-instance configuration without code changes. The parameter values are supplied when the script is embedded.

Changing a script's parameter set requires Wix users who have the app installed to update the app to receive the new version.

Script execution

Once embedded, a script's HTML fragment is injected into the site's DOM and runs on the published site. Script execution can happen before the DOM has fully loaded, so scripts that touch the DOM need to wait for it to be ready before running.

Authentication and permissions

Embedded script code runs on the published site with the identity of the person viewing the page (a visitor or member), the same as other site extensions. Elevation isn't available in the browser; to call APIs that require Wix app authentication, route the work through a backend handler and elevate there. The Site API host module is only available to embedded scripts created with the Wix CLI.

Embedded scripts across development paths

• Sites: Add scripts directly through the custom code feature in the Wix Editor or with the JavaScript SDK, not through the site extension framework.
• Wix-managed headless projects: Don't use embedded scripts. Headless projects use a custom frontend, so there's no Wix-rendered site DOM to inject into. Add scripts directly to your own frontend code.
• Self-managed headless projects: Don't use embedded scripts. Headless projects use a custom frontend, so there's no Wix-rendered site DOM to inject into. Add scripts directly to your own frontend code.
• Wix-managed apps: Add embedded scripts with the Wix CLI. See Add Embedded Script Extensions with the Wix CLI.
• Self-managed apps: Configure embedded scripts through the JSON editor in the App Dashboard. See Add an Embedded Script Extension to a Self-Hosted App in Build Apps.
• Blocks apps: Don't support embedded scripts.