Widget SDK

Embed a MeltingSpot Widget into your own web application: inline, as a modal, or as a drawer.

Installation

Via <script> (CDN)

The standalone bundle is self-contained: it exposes window.MeltingSpot.Widget and injects its styles automatically (no separate stylesheet to load).

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

Via npm

npm install @meltingspot/widget

import { Widget } from '@meltingspot/widget';
import '@meltingspot/widget/stylesheet.css';

Authentication (authToken)

authToken is the current user's MeltingSpot SSO token. Provide it to render the widget as an authenticated member; omit it to show only public content to an anonymous visitor. Activate SSO on your spot to obtain these tokens.

Rendering modes

The SDK offers three ways to render a widget, depending on how much control you want:

| Mode | Methods | Behaviour | | ---------- | ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | Inline | injectWidgetInto | Renders the widget immediately inside a container element you provide. Always visible, part of the layout. | | Modal | bindWidgetModalTo / createWidgetModal | Renders the widget in a centered overlay opened on demand. bind* wires it to a trigger; create* returns a handle you open/close yourself. | | Drawer | bindWidgetDrawerTo / createWidgetDrawer | Renders the widget in a side panel sliding from the left or right. Same bind* vs create* distinction. |

bind* methods attach the open behaviour to an existing element (e.g. a button), with zero extra wiring. create* methods return a Modal / Drawer instance with .open() / .close() so you drive visibility from your own code.

Inline

<div id="meltingspot-widget" style="width: 100%; height: 100%"></div>
<script>
  window.addEventListener('DOMContentLoaded', function () {
    window.MeltingSpot.Widget.injectWidgetInto('meltingspot-widget', {
      spotId: 'YOUR_SPOT_ID',
      widgetId: 'YOUR_WIDGET_ID',
      authToken: 'CURRENT_USER_SSO_TOKEN', // optional: omit for public content
      themeMode: 'auto',
    });
  });
</script>

Modal (bound to a trigger)

<button id="open-widget-modal" type="button">Open</button>
<script>
  window.addEventListener('DOMContentLoaded', function () {
    window.MeltingSpot.Widget.bindWidgetModalTo('open-widget-modal', {
      spotId: 'YOUR_SPOT_ID',
      widgetId: 'YOUR_WIDGET_ID',
      authToken: 'OPTIONAL_SSO_TOKEN',
      themeMode: 'auto',
    });
  });
</script>

Drawer (bound to a trigger)

<button id="open-widget-drawer" type="button">Open</button>
<script>
  window.addEventListener('DOMContentLoaded', function () {
    window.MeltingSpot.Widget.bindWidgetDrawerTo('open-widget-drawer', {
      position: 'right', // 'left' | 'right' (required)
      spotId: 'YOUR_SPOT_ID',
      widgetId: 'YOUR_WIDGET_ID',
      authToken: 'OPTIONAL_SSO_TOKEN',
      themeMode: 'auto',
    });
  });
</script>

Programmatic modal / drawer (create*)

When you need to open or close the widget from your own logic, create a handle:

import { Widget } from '@meltingspot/widget';

const drawer = Widget.createWidgetDrawer({
  spotId: 'YOUR_SPOT_ID',
  widgetId: 'YOUR_WIDGET_ID',
  authToken: 'OPTIONAL_SSO_TOKEN',
});

drawer.open(); // slide in
drawer.close(); // slide out

// Same API for a modal:
const modal = Widget.createWidgetModal({
  spotId: 'YOUR_SPOT_ID',
  widgetId: 'YOUR_WIDGET_ID',
});
modal.open();

Parameters

Common (all methods)

Fields of the options object (the last argument of every method).

| Option | Type | Required | Default | Description | | --------------- | ----------------------------------------- | -------- | --------------------------------- | ----------------------------------------------------------------------------------------- | | spotId | string | Yes* | n/a | Target spot id. *Optional on inject*/bind* if set via config; required on create*. | | widgetId | string | Yes | n/a | Target widget id. | | authToken | string | No | none (public content) | Current user's MeltingSpot SSO token. | | themeMode | 'auto' \| 'system' \| 'light' \| 'dark' | No | 'auto' | Force a theme. | | 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 widget URL. | | rootDocument | Document | No | current document | Document to inject into. |

Method-specific

Each method takes a positional target argument followed by the options object. The tables below list the positional target and the method-specific options.* fields; the common fields above apply to every method's options.

injectWidgetInto(target, options)

| Parameter | Type | Required | Default | Description | | --------- | ------------------- | -------- | ------- | -------------------------------------- | | target | string \| Element | Yes | n/a | Container the widget is rendered into. |

bindWidgetModalTo(target, options)

| Parameter | Type | Required | Default | Description | | -------------- | ------------------- | -------- | --------------- | ------------------------------------ | | target | string \| Element | Yes | n/a | Element whose click opens the modal. | | options.into | string \| Element | No | document.body | Where the modal mounts. |

bindWidgetDrawerTo(target, options)

| Parameter | Type | Required | Default | Description | | ------------------ | ------------------- | -------- | --------------- | ------------------------------------- | | target | string \| Element | Yes | n/a | Element whose click opens the drawer. | | options.position | 'left' \| 'right' | Yes | n/a | Side the drawer slides from. | | options.into | string \| Element | No | document.body | Where the drawer mounts. |

createWidgetModal(options) / createWidgetDrawer(options)

No method-specific parameters: they take the common options only and return a handle with .open() / .close().

domain

The custom domain key of your spot. It is forwarded to the widget so the internal 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 widget 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. |

See the Widget helpdesk for the full integration guide.