@meltingspot/meltingspot-js

v0.10.1

Published

10 days ago

MeltingSpot Javascript SDK

0High
0Medium
0Low

tech_meltingspot

fabien_ms

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 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>
  <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>
  <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.

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>
  <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>
  <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>
  <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>
  <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.

onReady?: () => void;

onError

Called when a loading error occurs inside the iframe.

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>
  <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:

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);
  },
});

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Table of contents