Embed SDK

Embed a full MeltingSpot spot into your own web application through an iframe, with lifecycle callbacks and theming.

Installation

Via <script> (CDN)

The standalone bundle is self-contained: it exposes window.MeltingSpot.Embed.

<script
  crossorigin
  src="https://cdn.jsdelivr.net/npm/@meltingspot/embed"
></script>

Via npm

npm install @meltingspot/embed

import { Embed } from '@meltingspot/embed';

Usage

Add a container element and inject your spot into it:

<div id="meltingspot-frame" style="width: 100%; height: 100%"></div>
<script>
  window.addEventListener('DOMContentLoaded', function () {
    window.MeltingSpot.Embed.injectSpotInto('meltingspot-frame', {
      spotId: 'YOUR_SPOT_ID',
      authToken: 'CURRENT_USER_SSO_TOKEN',
      themeMode: 'auto',
    });
  });
</script>

The programmatic equivalent:

import { Embed } from '@meltingspot/embed';

Embed.injectSpotInto('meltingspot-frame', {
  spotId: 'YOUR_SPOT_ID',
  authToken: 'CURRENT_USER_SSO_TOKEN',
  themeMode: 'auto',
});

Authentication (authToken)

authToken is the MeltingSpot SSO token of the current user. Provide it to embed the spot as an authenticated member, so the user sees the same content and permissions as inside MeltingSpot. Activate SSO on your spot to obtain these tokens.

Omit authToken to embed in public mode: only publicly available content is shown and the visitor is treated as anonymous.

injectSpotInto(target, options)

target (required) is the container: an element id (string) or an HTMLElement.

| Option | Type | Required | Default | Description | | --------------- | ----------------------------------------- | -------- | --------------------------------------------- | --------------------------------------------------------- | | spotId | string | Yes | n/a | Target spot id. Required here unless set via the config. | | authToken | string | No | ms_token URL param, else none (public mode) | Current user's MeltingSpot SSO token. | | themeMode | 'auto' \| 'system' \| 'light' \| 'dark' | No | 'auto' | Force a theme. | | deeplink | string | No | ms_url URL param, else none | In-spot page opened on load. See deeplink. | | domain | string | No | none (default MeltingSpot domain) | Custom domain key of your spot. See domain. | | utmParameters | UtmParameters | No | parsed from the page URL params | UTM params appended to the embed URL. | | rootDocument | Document | No | current document | Document to inject into. | | onReady | () => void | No | none | Called when the embedded content is fully rendered. | | onError | (error) => void | No | none | Called on a loading error inside the iframe. |

deeplink

The in-spot page the embed opens on load (a path or URL, e.g. a channel, course or post). It is normalized to the spot route (/spot/{spotId}/...), preserving the query string and hash.

If omitted, the SDK auto-detects a deeplink from the ms_url query param that MeltingSpot injects into the links generated by the app (e.g. links sent in emails). Setting deeplink explicitly disables that automatic detection and forces your value instead.

See the embed guide for details.

domain

The custom domain key of your spot. It is forwarded to the embedded content so the links it generates point to your custom domain instead of the default MeltingSpot one.

See the "Multi-domains" section of the embed guide for details.

UtmParameters

Appended to the embed URL as utm_* query params (source becomes utm_source, etc.).

| Field | Type | Required | Default | Description | | ---------- | -------- | -------- | ------- | --------------------- | | source | string | Yes | n/a | utm_source value. | | medium | string | No | unset | utm_medium value. | | campaign | string | No | unset | utm_campaign value. | | term | string | No | unset | utm_term value. | | content | string | No | unset | utm_content value. |

Lifecycle callbacks

onReady / onError are backed by postMessage signals (meltingspot:ready / meltingspot:error) with origin validation.

Embed.injectSpotInto('meltingspot-frame', {
  spotId: 'YOUR_SPOT_ID',
  authToken: 'CURRENT_USER_SSO_TOKEN',
  themeMode: 'auto',
  onReady: () => console.info('MeltingSpot embed is ready'),
  onError: (error) => console.error('MeltingSpot embed error:', error.message),
});

The error object passed to onError:

| Property | Type | Description | | --------- | -------- | --------------------------------- | | type | string | Optional error type | | message | string | Human-readable error message | | code | string | Optional error code for debugging |

See the Embed helpdesk for the full integration guide.