In This Article

Embedded Script Extension Files and Code

When you add an embedded script extension, the generated files land under src/extensions/site/embedded-scripts/<script-folder>/ and the extension is registered in your project's extensions.ts.

A Studio Two site project and a Wix CLI project both generate a configuration file and an HTML fragment. A Studio Two project also generates logger.ts, and the generated HTML loads that file.

Copy

File	What it's for
`<script-folder>.extension.ts`	The configuration file for the script ID, name, placement, script type, and HTML path. Generated in Studio Two and Wix CLI projects.
`<script-folder>.html`	The HTML fragment injected into the page. Generated in Studio Two and Wix CLI projects.
`logger.ts`	Studio Two only. A local module the generated HTML loads. Replace it, or remove the script tag that loads it.

Configuration file

The <script-folder>.extension.ts file declares the script with extensions.embeddedScript().

Import extensions from the package your project uses:

Copy

Keep this file. If you add an embedded script yourself, include it. Don't delete it after the script is generated.

Configuration fields

Field	Type	Description
`id`	string	Script ID as a GUID. It must be unique across embedded scripts in the project. When an app has more than one embedded script, pass this value as the component ID to the Embed Script API.
`name`	string	The display name for the script. In Studio Two, Generate also uses this name to derive the folder and file name.
`scriptType`	enum	Consent category. `ESSENTIAL` is core functionality and doesn't require consent. `FUNCTIONAL` remembers visitor choices, such as language. `ANALYTICS` reports usage data, such as Google Analytics. `ADVERTISING` provides visitor data for marketing, such as a retargeting tag. If a script fits more than one type, use the most restrictive type. A script used for analytics and advertising should be `ADVERTISING`.
`placement`	enum	Where the HTML is injected. `HEAD` places it in the page head, for tags that must load before the page renders. `BODY_START` places it immediately after the opening body tag, so it runs before page content. `BODY_END` places it at the end of the body, so it runs after page content. `BODY_END` is the safest default.
`source`	string	Path to the HTML fragment, relative to the project's `src/` directory. For example, `./extensions/site/embedded-scripts/my-script/my-script.html`.

HTML fragment

The <script-folder>.html file is the fragment injected at the placement you set. A generated fragment logs a greeting that includes a dynamic parameter:

Copy

In a Studio Two project, the generated fragment also loads logger.ts:

Copy

You can include script, style, and link tags in this file. Styles in the fragment apply on the pages where the script loads.

Dynamic parameters

A dynamic parameter is a placeholder the platform replaces per installation, so the same fragment can carry per-site configuration. In the generated fragment, {{name}} is a dynamic parameter.

A dynamic parameter must follow these rules:

The value is a string.
The name uses only letters and numbers, with no spaces or other characters.
The placeholder is wrapped in double curly braces, like {{accountId}}.
The placeholder sits inside quotes, so the page doesn't treat it as code.

The names in the HTML must match the names you pass when the script is embedded. Supply the values with the Embed Script API. Changing the parameter set requires Wix users who have the app installed to update the app before they receive the new version.

For example, a pixel script can take an account ID:

Copy

Local script files

Wix hosts the files in the script folder. The HTML can load one with a relative path. A script tag that points at a local file needs type="module".

Copy

TypeScript files are supported.

In a Studio Two project, the generated logger.ts is that module:

Copy

You can replace logger.ts with your own module, or remove the tag if the fragment doesn't need a separate file. In a Wix CLI project, add your own module when the HTML should load a local file.

Troubleshooting

The MISMATCHED ANONYMOUS DEFINE() MODULES error is common with AMD or UMD bundled scripts. It happens when an embedded script defines an anonymous module. That can be the embedded script itself, if it is bundled with AMD or UMD, or a script tag the embed adds to the head that contains an anonymous module.

To resolve the issue, try the following:

The embedded script itself: If the script is bundled with AMD or UMD, declare only named modules.
A script you own that the embed loads: If that script is bundled with AMD or UMD, declare only named modules.
A script you don't own: Check whether requirejs exists on window. If it does, load the script through requirejs instead of adding it to the head. This can still race, and it can still error.

For more on this error, see RequireJS: Common Errors.