Set up an Embedded Script Extension

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.

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
    1
    npm run generate

    Note: If the command fails, check that your package.json includes the "generate": "wix app generate" script. If it's missing, add it and rerun the command. Even if your CLI packages are up to date, your project might have been created with a version of CLI that didn't include the script.

    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:

Copy
1
.
2
└── <your-app-name>/
3
    └── src/
4
        └── site/
5
            └── embedded-scripts/
6
                └── <your-script-name>/
7
                    ├── embedded.html
8
                    ├── embedded.json
9
                    └── params.dev.json
  • 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.

Note: This step has covered the basics of setting up an embedded script extension. For more information about how you can customize your embedded script, read Embedded Script Extension Files and Code

Step 2 | Prepare your app for production

To finish setting up your embedded script, either you or the site owner must call the Embed Script 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.

Note: If an app 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.

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 statements at the top of your page:

    Copy
    1
    import { useWixModules } from '@wix/sdk-react';
    2
    import { embeddedScripts } from '@wix/app-market';

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

    Copy
    1
    const { embedScript } = useWixModules(embeddedScripts);

  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
    1
    await embedScript({
    2
       parameters: {
    3
         "<your-key-1>": "<your-value-1>"
    4
       }
    5
    })

    Warning: If your app has more than 1 embedded script, you cannot use the Wix React SDK's embedScript() endpoint. You must use the REST Embed Script endpoint instead.

    Click to expand instructions on calling the REST Embed Script endpoint

    You can call the REST Embed Script endpoint using the fetch method 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 the fetch method 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
      1
      import { useWix } from "@wix/sdk-react";

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

      Copy
      1
      const { fetch } = useWix();

    4. Add the fetch 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 fetch method.

      If your app contains only one embedded script, the fetch method call should be in the following format:

      Copy
      1
      ```tsx
      2
       fetch('https://www.wixapis.com/apps/v1/scripts', {
      3
         method : 'post',
      4
         headers : {'content-type':'application/json'},
      5
         body : JSON.stringify({
      6
           "properties": {
      7
             "parameters": {
      8
               "<your-key-1>": "<your-value-1>",
      9
               "<your-key-2>": "<your-value-2>",
      10
             }
      11
           }
      12
         })
      13
       })
      14
       ```

      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
      1
      fetch('https://www.wixapis.com/apps/v1/scripts', {
      2
        method : 'post',
      3
        headers : {'content-type':'application/json'},
      4
        body : JSON.stringify({
      5
          "properties": {
      6
            "parameters": {
      7
              "<your-key-1>": "<your-value-1>",
      8
              "<your-key-2>": "<your-value-2>",
      9
            }
      10
          },
      11
          "componentId": <your-component-id>
      12
        })
      13
      })

      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 Wix Dev Center.

  1. Run the following command to build your app:

    Copy
    1
    npm run build

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

    Copy
    1
    npm run create-version

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.

For more information about the above commands, see Wix CLI Commands for Apps.

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 on the Wix Dev Center.
Was this helpful?
Yes
No