About the Custom Embeds API

The Custom Embeds API allows you to embed custom HTML and JavaScript code into specific positions on Wix site pages. This enables you to add custom functionality to enhance your site's capabilities.

With the Custom Embeds API, you can:

  • Create custom embeds with HTML and JavaScript code.

  • Position embeds in the page head or body tags.

  • Enable or disable embeds without deleting them.

  • Monitor embed changes through domain events.

Categories and loading behavior

Embeds are classified into categories that determine their loading behavior:

  1. ESSENTIAL

    • Critical functionality required for site operation.
    • Always loaded, regardless of user preferences.
    • Tags will be returned in the HTML immediately.
    • Examples: Core functionality scripts, required third-party integrations.
    • It's important to note that any tracking, marketing, or analytics scripts should never be categorized this way.

  2. FUNCTIONAL

    • Enhanced functionality that's not critical.
    • Can be loaded conditionally, based on user preferences.
    • Examples: Chat widgets, social media integrations.

  3. ANALYTICS

    • Tracking and measurement code.
    • Subject to user privacy preferences.
    • Examples: Google Analytics, conversion tracking.

  4. ADVERTISING

  5. DATA TO THIRD PARTY

    • Code that shares data with external services.
    • Requires careful handling for privacy compliance.
    • Examples: CRM integrations, data synchronization scripts.

Positioning for custom embeds

Custom embeds can be placed in 3 strategic locations:

  • HEAD: In the document's <head> section.
    • For resources that need to load before the page content.
    • Examples: Meta tags, CSS, early-loading scripts.
  • BODY_START: At the beginning of the <body> section.
    • For initialization code that runs before page content loads.
    • Examples: Scripts that need early access to DOM elements.
  • BODY_END: At the end of the <body> section.
    • For code that doesn't need to block page rendering.
    • Examples: Analytics, tracking scripts, non-critical functionality.

Before you begin

It's important to note the following points before starting to code:

  • You can create multiple custom embeds on a Wix site.
  • Each custom embed has a specific position on the page (HEAD, BODY_START, or BODY_END) that determines when and where the code is executed.
  • Embeds are only rendered on a site when enabled = true.
  • Each embed has a category property that determines how and when the embed is rendered based on user consent and site policies.
  • When duplicating a site, custom embeds are cloned as well.

Use cases

Terminology

  • Custom Embed: An entity that manages custom HTML and JavaScript code to be embedded in a site, along with its placement and properties.
  • Position: Where the embed code is inserted in the HTML document. Options are in the document head, at the beginning of the body, or at the end of the body.
  • Load Once: When enabled, the embed is loaded only once during initial site rendering, rather than on each page navigation.
  • Domain: Optionally specifies a domain which is connected to the site, that can be later used for organizing/managing your site's custom embeds.
  • Category: The classification of the embed that determines if it's loaded, based on user consent:
    • ESSENTIAL: Critical functionality required for the site to work properly.
    • FUNCTIONAL: Features that enhance site functionality but aren't critical.
    • ANALYTICS: Code for tracking and analytics purposes.
    • ADVERTISING: Code related to advertising and marketing.
    • DATA_TO_THIRD_PARTY: Code that shares data with external services.
Did this help?