Add an Embedded Script Extension to a Self-Hosted App

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 aren't fully configured by default during app installation and an extra step is required to embed the code fragment.

An example of an HTML code fragment is:

Copy

This article explains how to:

  1. Add an embedded script extension.
  2. Embed the script upon app installation.
  3. Test the embedded script on a demo site.

After following these steps, your app will have an embedded script extension that injects its HTML code fragment into the DOM of every page of your users' sites.

Step 1 | Add an embedded script extension

  1. Create a new app, or select an existing app from the Custom Apps page in your Wix Studio workspace.

  2. Go to Extensions and click +Create Extension.

  3. Find Embedded Script.

  4. Click Create.

  5. Name your extension. The name can only contain letters and the hyphen (-) character.

  6. Select a Script Type:

    • Essential: Enables site visitors to move around the website and use essential features like secure and private areas crucial to the functioning of the site.
    • Functional: Remembers choices site visitors make to improve their experience. For example, language.
    • Analytics: Helps site owners understand how visitors use their website by providing statistics, such as which pages they visit, and by identifying errors and performance issues.
    • Advertising: Lets site owners collect information to help market their products, such as data on the impact of marketing campaigns or re-targeted advertising.

    Site owners can allow visitors to choose whether to opt out of cookies and 3rd-party scripts. Sites check the script type against the user's consent settings to determine whether to run the script.

    Note: An embedded script can't be saved without a type. If your script falls into more than 1 type, choose the option closest to the bottom of the list above. For example, if your script has Advertising and Analytics aspects, choose Advertising as its type. It's unlikely that you'll need to mark it as Essential. If you think you need to use this, please get in touch with us.

  7. Write the custom code to embed, including any relevant dynamic parameters.

    • For efficiency, load the code from an external source so that you can edit the script on the external platform instead of within the extension. This ensures that changes, except for changes made to dynamic parameters, are automatically reflected across all app versions without needing individual reviews.

    • Your script may not run until after the DOM has fully loaded. Therefore, you should check whether the DOM has loaded before running your code.

      Example: Use the DOMContentLoaded event to check if the DOM has loaded
      Copy

    • To call APIs using the Wix JavaScript SDK, you need to authenticate using the Wix Client.

  8. Set up a dashboard page in the app dashboard for users to set up and customize the embedded script.

Step 2 | Embed the script upon app installation

Your app needs to make a POST request to enable the embedded script each time a user installs your app. To embed the script upon app installation:

  1. Create an access token. For more information, see Authenticate as an App Instance.

  2. Register to the App Instance Installed webhook. For guidance, see Handle Events With Webhooks.

  3. Upon receipt of the webhook, make a POST request to the Embed Script endpoint with the access token provided in the Authorization header of the request:

    • If your script includes dynamic parameters, include them in the request body under the parameters key:

      Copy

    • If your script doesn't include dynamic parameters, make the call with the following request body:

      Copy

    Tip: If your app uses the JavaScript SDK, you can embed the script with the embedScript() method.

  4. (Optional) If your app includes multiple embedded scripts, each request must specify the componentId in the request body sent to the Embed Script endpoint:

    Copy

    The componentId can be found within the URL of the embedded script page in your app's dashboard:

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

Now your embedded script will be injected into a site upon app installation.

Note: If you don't want to rely on the App Instance Installed webhook, you can call the Embed Script endpoint as part of the advanced OAuth installation flow. For more information, see About OAuth.

Step 3 | Test your script

To test your embedded script:

  1. Install your app on a premium site with a connected domain.

  2. Visit the test site where the app is installed. Inspect the site and check that the script appears in the site code. You can see the script in the network tab by filtering for "tags".

    Tip: If you don't see the script on the site, go to App > Manage Apps page within the site dashboard, and check that the script isn't disabled.

  3. If you used dynamic parameters, check that they exist in the script as expected.

For more information on testing, see App Checks and Testing Guide.

See also

Did this help?