npm package: @meltingspot/meltingspot-js
Description: MeltingSpot Javascript SDK
Latest version: 0.10.1

<h1 align="center">🚀 MeltingSpot Javascript SDK</h1>

# Table of contents

- [Table of contents](#table-of-contents)
- [Project description](#project-description)
- [Getting started](#getting-started)
  - [Installation](#installation)
  - [Usage](#usage)
    - [Embed Meltingspot into your own app](#embed-meltingspot-into-your-own-app)
    - [Embed a Meltingspot Widget into your own app](#embed-a-meltingspot-widget-into-your-own-app)
- [Lifecycle callbacks](#lifecycle-callbacks)
  - [onReady](#onready)
  - [onError](#onerror)
  - [Example](#example)

# Project description

The MeltingSpot Javascript SDK is a library that allows you to easily
integrate MeltingSpot into your Javascript application.

# Getting started

## Installation

Please check the [Embed helpdesk](https://help.meltingspot.io/manage-spot/embed) if you plan to embed MeltingSpot into your website through an iframe.

## Usage

First you should load this library from jsDelivr inside the `<head>` tag of your application:

```html
<html>
  <head>
    <!-- ... -->
    <script
      crossorigin
      async
      src="https://cdn.jsdelivr.net/npm/@meltingspot/meltingspot-js"
    ></script>
    <!-- ... -->
  </head>
  <body>
    <!-- ... -->
  </body>
</html>
```

### Embed Meltingspot into your own app

You just need to add an element into the DOM that will wrap the embed and use `window.MeltingSpot.injectSpotInto` to embed your spot into your own app:

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

### Embed a Meltingspot Widget into your own app

You will need to activate SSO in your spot before using this. You will find everything you need on the SSO activation [here](https://help.meltingspot.io/manage-spot/sso).

You just need to add an element into the DOM that will wrap the Widget and use `window.MeltingSpot.injectWidgetInto` to embed your Widget into your own app:

```html
<html>
  <head>
    <!-- ... -->
  </head>
  <body>
    <!-- ... -->
    <div id="meltingspot-widget" style="width:100%;height:100%"></div>
    <script>
      window.addEventListener('DOMContentLoaded', function () {
        window.MeltingSpot.injectWidgetInto('meltingspot-widget', {
          spotId: 'YOUR_SPOT_ID',
          widgetId: 'YOUR_WIDGET_ID',
          authToken: 'CURRENT_USER_MELTINGSPOT_SSO_TOKEN',
          themeMode: 'auto',
        });
      });
    </script>
    <!-- ... -->
  </body>
</html>
```

You can also embed the widget without providing an `authToken`, everyone will only see public content:

```html
<html>
  <head>
    <!-- ... -->
  </head>
  <body>
    <!-- ... -->
    <div id="meltingspot-widget" style="width:100%;height:100%"></div>
    <script>
      window.addEventListener('DOMContentLoaded', function () {
        window.MeltingSpot.injectWidgetInto('meltingspot-widget', {
          spotId: 'YOUR_SPOT_ID',
          widgetId: 'YOUR_WIDGET_ID',
          themeMode: 'auto',
        });
      });
    </script>
    <!-- ... -->
  </body>
</html>
```

Widgets can also be added as modal or drawer inside your app, you will need to bind it to a button:

```html
<html>
  <head>
    <!-- ... -->
  </head>
  <body>
    <!-- ... -->
    <button id="meltingspot-open-widget-modal" type="button"></button>
    <script>
      window.addEventListener('DOMContentLoaded', function () {
        window.MeltingSpot.bindWidgetModalTo('meltingspot-open-widget-modal', {
          spotId: 'YOUR_SPOT_ID',
          widgetId: 'YOUR_WIDGET_ID',
          authToken: 'OPTIONAL_CURRENT_USER_MELTINGSPOT_SSO_TOKEN',
          themeMode: 'auto',
        });
      });
    </script>
    <!-- ... -->
  </body>
</html>
```

```html
<html>
  <head>
    <!-- ... -->
  </head>
  <body>
    <!-- ... -->
    <button id="meltingspot-open-widget-drawer" type="button"></button>
    <script>
      window.addEventListener('DOMContentLoaded', function () {
        window.MeltingSpot.bindWidgetDrawerTo(
          'meltingspot-open-widget-drawer',
          {
            position: 'right', // or 'left'
            spotId: 'YOUR_SPOT_ID',
            widgetId: 'YOUR_WIDGET_ID',
            authToken: 'OPTIONAL_CURRENT_USER_MELTINGSPOT_SSO_TOKEN',
            themeMode: 'auto',
          },
        );
      });
    </script>
    <!-- ... -->
  </body>
</html>
```

# Lifecycle callbacks

Both `injectSpotInto` and `injectWidgetInto` accept optional lifecycle callbacks that let you react when the embedded content is ready or when a loading error occurs.

These callbacks rely on `postMessage` signals (`meltingspot:ready` / `meltingspot:error`) sent by the iframe content, with origin validation for security.

## onReady

Called when the embedded content is fully rendered inside the iframe.

```typescript
onReady?: () => void;
```

## onError

Called when a loading error occurs inside the iframe.

```typescript
onError?: (error: { type?: string; message: string; code?: string }) => void;
```

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

## Example

```html
<html>
  <head>
    <!-- ... -->
  </head>
  <body>
    <!-- ... -->
    <div id="meltingspot-frame" style="width:100%;height:100%"></div>
    <script>
      window.addEventListener('DOMContentLoaded', function () {
        window.MeltingSpot.injectSpotInto('meltingspot-frame', {
          spotId: 'YOUR_SPOT_ID',
          themeMode: 'auto',
          onReady: function () {
            console.info('MeltingSpot embed is ready');
          },
          onError: function (error) {
            console.error(
              'MeltingSpot embed error:',
              error.type,
              error.message,
              error.code,
            );
          },
        });
      });
    </script>
    <!-- ... -->
  </body>
</html>
```

The same callbacks are available for `injectWidgetInto`:

```javascript
window.MeltingSpot.injectWidgetInto('meltingspot-widget', {
  spotId: 'YOUR_SPOT_ID',
  widgetId: 'YOUR_WIDGET_ID',
  authToken: 'CURRENT_USER_MELTINGSPOT_SSO_TOKEN',
  themeMode: 'auto',
  onReady: function () {
    console.info('Widget is ready');
  },
  onError: function (error) {
    console.error('Widget error:', error.message);
  },
});
```