Function integrateMetabox

integrateMetabox(
    configuratorId: string,
    containerId: string,
    apiReadyCallback: (api: Communicator) => void,
    config?: IntegrateMetaboxConfig,
): () => void
Integrates the Metabox Modular Configurator into the page by injecting an iframe and initializing a Communicator instance for host-to-iframe messaging.
- Builds a secure iframe URL using the provided configuratorId and config options.
- Ensures the resulting URL uses HTTPS and that the target container exists.
- Removes any previously embedded iframe with id "embeddedContent" before inserting a new one.
What does it unlock?

Main initialization function for MetaBox integration. Initializes the configurator, receives an API handle, and sets up all configurations.

Practical Application

is THE entry point function. Creates the configurator iframe, establishes postMessage communication, and returns the Communicator api handle via callback. Call ONCE per configurator. Params: configuratorId (modular UUID), containerId (DOM element ID, default 'embed3DSource'), apiReadyCallback, config (IntegrateMetaboxConfig).

AI Coding Best Practices

Pattern: integrateMetabox('uuid', 'div-id', (api) => { set up listeners, then set a root component, then environment, then children }, { standalone: true }). Ensure a container div exists in DOM with non-zero dimensions. HTTPS required. Inside callback: 1) addEventListener for configuratorDataUpdated, 2) SetComponent root, 3) SetEnvironment, 4) SetComponent children, 5) SetComponentMaterial.
Parameters
- configuratorId: string
  The Modular Configurator ID (not a full URL). It is appended to https://{domain}/metabox-configurator/modular/{configuratorId} to form the iframe src.
- containerId: string
  The id of the container element where the iframe will be injected.
- apiReadyCallback: (api: Communicator) => void
  Called when the Communicator instance is created on the host side.
- Optionalconfig: IntegrateMetaboxConfig
  Optional configuration used to build the iframe URL and initialize the communicator. Supported fields:
  
  standalone?: boolean — if true, disables Metabox custom template and related logic.
  
  introImage?: string — URL to an image shown on the intro screen (added as ?introImage=...).
  
  introVideo?: string — URL to a video shown on the intro screen (added as ?introVideo=...).
  
  loadingImage?: string — URL to an image displayed while loading (added as ?loadingImage=...).
  
  state?: string — Predefined state for configurator for initial loading (added as ?state=...).
  
  domain?: string — custom domain for testing (defaults to metabox.3dsource.com). HTTPS is enforced.
  
  showLoadingProgress?: boolean — if true, shows the loading progress bar (added as ?showLoadingProgress=true).
  
  showResumeStreamPopup?: boolean — if true, shows the resume stream popup (added as ?showResumeStreamPopup=true).
  
  showUserInactivityTimer?: boolean — if true, shows the AFK countdown popup (added as ?showUserInactivityTimer=true).
  
  userInactivityTimeout?: number — inactivity timeout in seconds before disconnect (added as ?userInactivityTimeout=...).
Returns () => void
A cancel function that stops waiting for the Metabox to load. Calling it is optional — a later integrateMetabox call automatically supersedes a still-pending handshake — but it lets you remove the handshake listener immediately on teardown (e.g. SPA route change before apiReadyCallback fires). Idempotent.
Throws
Error If configuratorId or containerId are empty strings.

Throws
Error If the computed iframe URL is invalid or does not use HTTPS.

Throws
Error If the container element with the provided id cannot be found.
Example
```
import { integrateMetabox } from '@3dsource/metabox-modular-configurator-api';

integrateMetabox('configurator-id',
  'embed3DSource',
  (api) => {
    // Communicator is ready to use
  },
  {
    standalone: false,
    introImage: 'https://example.com/intro.png',
    loadingImage: 'https://example.com/loading.png',
    showLoadingProgress: true,
    showResumeStreamPopup: true,
    showUserInactivityTimer: true,
    userInactivityTimeout: 20,
  },
);
```

Function integrateMetabox

What does it unlock?

Practical Application

AI Coding Best Practices

Parameters

Returns () => void

Throws

Throws

Throws

Example

Settings

On This Page