Add an Embedded Script Extension with the Wix CLI

An embedded script is an app extension that injects an HTML code fragment into the DOM of your users' sites. Unlike other extensions, embedded scripts are not fully configured during app installation, and require an additional step to embed the code fragment.

Follow the instructions below to:

1. Create an embedded script extension for a Wix CLI app project.
2. Prepare your project for production.

Once this task is complete, your project will have an embedded script extension that injects its HTML code fragment into the DOM of every page of your users' sites.

Step 1 | Create the extension

In the terminal:

1. Navigate to your project repo.
2. Run the generate command and follow the prompts to create an embedded script extension. Select any script type and placement.

Upon completion, the extension files will be created in your project directory with the following structure:

Learn more about the embedded script extension files.

Step 2 | Load the embedded script in your code

Creating the extension in Step 1 only defines the script. It doesn't inject it into the site. To load the script into the site, either you or the Wix user must call the embedScript() method. Without this call, the script won't run on the site.

When calling this method, specify the parameters object with key-value pairs for any dynamic parameters referenced in your embedded script's HTML code. The parameter values are loaded when the method is called.

Let the site owner embed the script (recommended)

If your app project has a dashboard page, you have the option to shift responsibility for this last configuration step onto site owners.

This API call is also used to specify the value of any dynamic parameters. For more information about using dynamic parameters, see Using dynamic parameters in your HTML code.

To use embedScript() in your app's dashboard page:

1. Open the dashboard page component file in your src/dashboard/pages folder.

   Note: By default, the CLI generates this file as page.tsx with a component named Index, but you may have renamed these during setup.

2. Add the following import statement at the top of your page:

   Copy

3. Inside your dashboard page component, add the following code before the return statement:

   Copy

4. Add the Embed Script call somewhere in your component's code. For example, add a call to action with instructions to click a button to complete your setup. Then, when the site owner clicks the button, they call the method.

   If your project contains only one embedded script, call the method in the following format:

   Copy

   If your app contains more than one embedded script, you must also pass a componentId using the id value defined in the script's .extension.ts file (the id property in the extensions.embeddedScript() call). In this situation, your call should be in the following format:

   Copy

   Note: On the Extensions page in the app dashboard, this ID is called extension ID.

   Make sure parameters contains all the dynamic parameters referenced in your embedded script. Omitting a parameter results in an error, and the script isn't embedded.

   Warning: If your project only has 1 embedded script, don't pass the componentId in the request body. This action could break your app in production. The componentId is only relevant for projects with more than 1 embedded script.

Example component:

For a practical example of this configuration, see the Mixpanel Analytics template.

Embed a script as an app developer

You can also call the Embed Script method from your server once the app is installed on a user's site. This requires an access token obtained through the OAuth process.

Build and deploy your project

Once your project is ready, you can build and deploy it.

For more information about building and deploying your app, see Build and Deploy an App with the CLI.

Delete an embedded script extension

To delete an existing embedded script extension from your app:

1. Delete the folder that contains your embedded script's files.
2. Remove the import and .use() statements for the extension from the extensions.ts file.

See also

• Embedded Script Extension Files and Code
• Embed Script API reference
• Analyze User Behavior Using Embedded Scripts