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.

   During the creation process you will be prompted to select a script type and a placement. For this guide, you can make any selection. For more information, see the script type and placement options.

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 | Prepare your project for production

To finish setting up your embedded script, either you or the site owner must call the embedScript() method to embed your script and update the values of the dynamic parameters in each app instance.

Prompting the site owner to embed the code (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 page.tsx file in your src/dashboard/pages folder.

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

   Copy

3. Inside the dashboard page's Index component, add the following code before the return statement:

   Copy

4. Add the embedScript() 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 will call the method.

   If your project contains only one embedded script, the method should be called 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 your embedded.json file. In this situation, your call should be in the following format:

   Copy

   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.

Ensure that parameters contains all the dynamic parameters in your embedded script. Otherwise, you will get an error and your code will not be embedded.

Example component:

Although we are setting it up now, the Embed Script call won't work until you have deployed your project and released a version of your app, as documented below.

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

Embedding 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 for production, 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.