> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: Add an Embedded Script Extension

## Article: Add an Embedded Script Extension with the Wix CLI

## Article Link: https://dev.wix.com/docs/wix-cli/guides/extensions/site-extensions/embedded-scripts/add-an-embedded-script-extension.md

## Article Content:

# 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](https://dev.wix.com/docs/wix-cli/command-reference/project-commands/generate.md) command and follow the prompts to create an embedded script extension. Select any [script type and placement](https://dev.wix.com/docs/wix-cli/legacy-clis/legacy-wix-cli-for-apps/supported-extensions/site-extensions/embedded-scripts/embedded-script-extension-files-and-code.md).

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

```bash
src/
  └── extensions/
      └── site/
          └── embedded-scripts/
              └── <your-script-name>/
                  ├── <your-script-name>.extension.ts
                  └── <your-script-name>.html
```

> **Note:** This is the default folder structure created by the CLI. You can move these files to any location within the `src/` folder and update the references in your `extension.ts` file. Learn more about the [flexible file system](https://dev.wix.com/docs/wix-cli/guides/get-started/project-structure.md#your-custom-extension-folder).

Learn more about the [embedded script extension files](https://dev.wix.com/docs/wix-cli/guides/extensions/site-extensions/embedded-scripts/embedded-script-extension-files-and-code.md).

## 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()`](https://dev.wix.com/docs/api-reference/app-management/embedded-scripts/embed-script.md) 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](https://dev.wix.com/docs/wix-cli/guides/extensions/site-extensions/embedded-scripts/embedded-script-extension-files-and-code.md#using-dynamic-parameters-in-your-html-code) 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.

> **Note**: If an app project has a dashboard page and an embedded script extension, site owners will automatically be directed to the app's dashboard page after installing the app.

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](https://dev.wix.com/docs/wix-cli/guides/extensions/site-extensions/embedded-scripts/embedded-script-extension-files-and-code.md#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:

   ```tsx
   import { embeddedScripts } from "@wix/app-management";
   ```

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

   ```tsx
   const { embedScript } = embeddedScripts;
   ```

4. Add the [`Embed Script`](https://dev.wix.com/docs/api-reference/app-management/embedded-scripts/embed-script.md) 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:

   ```tsx
   await embedScript({
     parameters: {
       "<your-key-1>": "<your-value-1>",
     },
   });
   ```

   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:

   ```tsx
   await embedScript(
     {
       parameters: {
         "<your-key-1>": "<your-value-1>",
         "<your-key-2>": "<your-value-2>"
       }
     },
     {
       options: {
         "componentId": <your-component-id>
       }
     }
   )
   ```
   
   > **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.

   <blockquote class="warning">

   **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.

   </blockquote>

**Example component:**

```tsx
const Index: FC = () => {

  const { embedScript } = embeddedScripts;

  async function handleButtonClick(){
    dashboard.showToast({
      message: 'Embedded script activated!',
    });

    await embedScript({
      parameters: {
        "<your-key-1>": "<your-value-1>",
      },
    });
  }
  return (
    // Your component code with a button that uses an onClick handler to call handleButtonClick.
  );
};
```

<blockquote class="important">

**Important:**
The `Embed Script` call won't work until you run [`release`](https://dev.wix.com/docs/wix-cli/command-reference/project-commands/release.md) to create an app version. The `release` command registers your embedded script component in your app's configuration. Running `preview` alone uploads your code but does not register extensions. See [Build and Deploy](#build-and-deploy-your-project).

</blockquote>

For a practical example of this configuration, see the [Mixpanel Analytics template](https://github.com/wix/cli-app-templates/tree/master/mixpanel-analytics).

### Embed a script as an app developer

You can also call the [Embed Script](https://dev.wix.com/docs/api-reference/app-management/embedded-scripts/embed-script.md) method from your server once the app is installed on a user's site. This requires an access token obtained through the [OAuth process](https://dev.wix.com/docs/build-apps/develop-your-app/access/authentication/about-oauth.md).

## Build and deploy your project

Once your project is ready, you can [build and deploy](https://dev.wix.com/docs/wix-cli/guides/development/build-and-deploy-a-project.md) it.

> **Note:**
> When you release an app project, you release a new version of the app allowing you to publish the app to the [Wix App Market](https://www.wix.com/app-market) or install it on a site with a direct install URL. You can view [your app's versions](https://manage.wix.com/app-selector?title=Select+an+App&primaryButtonText=Select+Site&actionUrl=https%3A%2F%2Fdev.wix.com%2Fapps%2F%7BappId%7D%2Fversions-app) in the app dashboard.

For more information about building and deploying your app, see [Build and Deploy an App with the CLI](https://dev.wix.com/docs/wix-cli/guides/development/build-and-deploy-a-project.md).

## 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`](https://dev.wix.com/docs/wix-cli/guides/extensions/about-the-extensions-ts-file.md) file.

<blockquote class="important">

__Important:__
If you've already created a version of your app, deleting an embedded script's files from your project does not remove the embedded script from your app's latest version in the app dashboard. To remove the embedded script, create a new version after deleting the [embedded script's files](https://dev.wix.com/docs/wix-cli/guides/extensions/site-extensions/embedded-scripts/embedded-script-extension-files-and-code.md).

</blockquote>

## See also

- [Embedded Script Extension Files and Code](https://dev.wix.com/docs/wix-cli/guides/extensions/site-extensions/embedded-scripts/embedded-script-extension-files-and-code.md)
- [Embed Script API reference](https://dev.wix.com/docs/api-reference/app-management/embedded-scripts/embed-script.md)
- [Analyze User Behavior Using Embedded Scripts](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/site-extensions/embedded-scripts/analyze-user-behavior-using-embedded-scripts.md)