Add an Embedded Script Extension Using 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 setup step to embed the code fragment.

Follow the instructions below to:

1. Create an embedded script extension for a Wix CLI app.
2. Prepare your app for production.
3. Build and deploy your app.

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

Before you begin

• You must have an app project that was created using the Wix CLI.
• You must be logged into your Wix Developer account. If you don’t already have one, sign up for a Wix Developer account.

Step 1 | Create the extension

In the terminal:

1. Navigate to your project repo.

2. Run the following command and follow the prompts to create an embedded script extension:

   Copy

   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 app directory with the following structure:

• embedded.html - This file contains the HTML code fragment for your embedded script.
• embedded.json - This file contains information about your embedded script.
• params.dev.json - This file contains values for dynamic parameters to use during testing.

Step 2 | Prepare your app for production

To finish setting up your embedded script, either you or the site owner must call the embedScript() endpoint 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 has a dashboard page, you have the option to shift responsibility for this last configuration step onto site owners.

Site owners can call embedScript() from the Wix React SDK.

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 app’s src/dashboard/pages folder.

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

   Copy

3. Inside the Index method, add the following code:

   Copy

4. Add the embedScript() call somewhere in your code.

   For example, add a call to action with instructions to click a button to complete setup for your app. Then, when the site owner clicks the button, they will call the endpoint.

   If your app contains only one embedded script, the endpoint 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 app 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 apps 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.

Although we are setting it up now, the Embed Script call will not work until you have created an app version, 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 endpoint from your server once the app is installed on a user's site. This requires an access token obtained through the OAuth process.

Step 3 | Build and deploy your app

Now that your app is ready for production, you can build your app and create a version in the app dashboard.

1. Run the following command to build your app:

   Copy

2. Run the following command and follow the prompts to create an app version:

   Copy

An app version allows you to publish an app to the Wix App Market or install it on a site with a direct install URL. You can view your app versions in the app dashboard.

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

Summary

By following these instructions, you have:

1. Created and configured an embedded script extension for your application.
2. Provided a method to embed your extension’s HTML code fragment on your users' sites. When site owners download your app and complete the setup process, your code will be injected into the DOM of every page on their site.
3. Built your app and created a version.

See also

• Tutorial | Build a Locations App Using the Wix CLI