EMBEDDED SCRIPT

Use wix generate --params with all 5 required fields:

The CLI generates the folder, <folder>.html (the actual script HTML), the builder file, the UUID, and the src/extensions.ts registration. (It may also drop a sample <other>.ts module to demonstrate <script type="module" src="./xxx.ts"> imports — feel free to delete or repurpose it.)

After implementation, the app developer must enable SCOPE.DC-APPS.MANAGE-EMBEDDED-SCRIPTS in the Wix Dev Center — see Enable Embedded Script Permission.

Script Types

Embedded scripts must declare a type for consent management:

Selection rule: If a script falls into multiple types, choose the option closest to the bottom of the list (most restrictive). For example, a script with both Analytics and Advertising aspects should be typed as ADVERTISING.

Placement Options

Dynamic Parameters and Dashboard Configuration

Every embedded script requires a companion dashboard page to configure its parameters. Scaffold a separate DASHBOARD_PAGE extension and use embeddedScripts from @wix/app-management to load/save parameters (see DASHBOARD_PAGE.md). Wix stores the parameters and injects them as {{templateVars}} into the HTML at render time.

Parameter Types

Template Variable Syntax

{{parameterKey}} placeholders are substituted at injection time, but only inside HTML attribute values — not inside <script> bodies. The required pattern is: render every parameter as a data attribute on a config element, then read it from dataset in JS.

Type handling (all dataset values are strings):

• NUMBER → Number(value) or parseInt(value, 10)
• BOOLEAN → compare against "true" / "false"
• DATE / DATETIME → new Date(value)

Other rules:

• Template variable names must match the parameter keys exactly.
• Required parameters always have values; optional parameters may be empty — provide fallbacks.
• Only use parameters that are relevant to the use case; don’t reference parameters you don’t implement.

Common Parameters

Every embedded script should have at minimum an enable/disable toggle parameter:

Module-script Rules

The <script type="module"> block runs at module scope, where Rollup (used by Astro) disallows return statements.

• Use throw new Error(...) for early exits at module scope (e.g., “script disabled” / “config element not found”).
• Wrap the main logic in a named async function and call it from a DOMContentLoaded listener (or directly if document.readyState !== "loading"); return is valid inside the function.

See the Complete Example below for the full skeleton.

Examples

Analytics Tracking

Request: “Add Google Analytics tracking to my site”

Output:

• Script type: ANALYTICS
• Placement: HEAD
• Template variables: {{trackingId}}
• Implements: gtag.js initialization, page view tracking

Popup/Modal

Request: “Create a coupon popup that shows when cart value exceeds $50”

Output:

• Script type: FUNCTIONAL
• Placement: BODY_END
• Template variables: {{couponCode}}, {{minimumCartValue}}, {{enablePopup}}
• Implements: Cart value detection, popup display logic, localStorage for “don’t show again”

Third-Party Chat Widget

Request: “Integrate Intercom chat widget”

Output:

• Script type: FUNCTIONAL
• Placement: BODY_END
• Template variables: {{appId}}, {{userEmail}}, {{userName}}
• Implements: Intercom SDK initialization, user identification

Best Practices

• Always create a dashboard page: Every embedded script needs a configuration UI
• Include enable/disable toggle: Let site owners control activation without removing the script
• Performance: Minimize impact - scripts should be lightweight and non-blocking
• Security: Avoid inline event handlers, validate data, escape user input
• Error handling: Fail silently when appropriate - don’t break the site
• Module scope early exits: Use throw new Error() for early exits at module scope, not return. Rollup (used by Astro) doesn’t allow return statements at module scope. Wrap main logic in a named async function where return is valid.
• Type conversions: Parameters are always strings - convert in JavaScript as needed
• API calls: Only create fetch() calls to /api/* endpoints that exist in the API spec
• Scoping: Prefix CSS classes and IDs to avoid conflicts with site styles
• Cleanup: Remove event listeners and intervals when appropriate

Complete Example: Coupon Popup

1. Define Parameters

2. Embedded Script (<folder>.html)

3. Dashboard Page (See the DASHBOARD_PAGE.md reference)

Uses embeddedScripts API from @wix/app-management:

Enable Embedded Script Permission

After implementation, the app developer must manually enable the embedded script permission:

1. Go to https://manage.wix.com/apps/{app-id}/dev-center-permissions (opens in a new tab) (replace {app-id} with your actual app ID)
2. Add the SCOPE.DC-APPS.MANAGE-EMBEDDED-SCRIPTS permission
3. Save the changes

Note: This is a manual step in the Wix Dev Center. Without this permission, embedded scripts will not function on the site.