About the Embedded Script API

You can use the Embedded Script API to inject custom script tags to the head tag of a site.
If you have custom keys or data, you can use dynamic parameters in your embedded script.
You can also listen to predefined Wix events, and report and listen to custom events.

Using dynamic parameters

The embedded script can include dynamic parameters. For example:

<script type=“text/javascript” id=“xyz-script-loader” async defer src=“//js.hs-scripts.com/{{abcid}}.js”></script>

Before you begin

  • You must authenticate as a Wix App.
  • If an app has more than one embedded script component, the relevant component ID must be passed for all calls. The component ID for each embedded script component is available as a query parameter in the embedded script's extension page in the app dashboard.
  • If an app only has one embedded script component, don't pass the component ID.
  • The keys in the custom parameters passed in this API must be identical to the keys defined in the app's embedded script component. Using any other keys results in a 400 error.
  • Dynamic parameters must:
    • Be strings.
    • Contain only alphanumeric characters (no special characters or spaces).
    • Be wrapped in double curly braces ({{).
    • Be enclosed in quotes (") to prevent code evaluation.
    • Be provided upon installation when calling Embed Script.

Use cases

Troubleshooting

The MISMATCHED ANONYMOUS DEFINE() MODULES... error is a common issue when working with AMD/UMD bundled scripts. The error occurs when an embedded script defines an anonymous module, either because it's bundled with AMD or it adds a script tag to the head containing an anonymous module.

To resolve the issue, try the following:

  • For the embedded script itself: If the script is bundled with AMD/UMD, make sure that you declare only named modules.
  • For scripts loaded by the embed:
    • If you own the code: If the scripts are bundled with AMD/UMD, make sure that you declare only named modules.
    • If you don't own the code: Check if requirejs exists on the window. If it does, load the script via requirejs instead of adding the script to the <head>. This approach is suboptimal and might still lead to race conditions and errors.

For more information on this issue, see RequireJS: Common Errors.

Did this help?

Script Properties Object

Properties
parametersMap <string, string>format map

Script parameters.

disabledboolean

Whether script is disabled or not. Default: false (not disabled).

Did this help?
GET

Get Embedded Script

Retrieves information about your app's existing embedded script.

If your app doesn't have an embedded script on the relevant site, a 404 error is returned.

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage Embedded Scripts
Learn more about app permissions.
Endpoint
GET
https://www.wixapis.com/apps/v1/scripts
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?
POST

Embed Script

Inserts custom script tags into a site, with the specified values for any dynamic parameters. Call this method when your app is installed on a site.

Your app must have an existing embedded script component, with exactly matching parameter names.

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage Embedded Scripts
Learn more about app permissions.
Endpoint
POST
https://www.wixapis.com/apps/v1/scripts
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?