Coach SDK

MeltingSpot's contextual guidance SDK. It displays the AI coach (proactive conversations and content such as courses, lives, documents and learning paths) directly inside your web application, triggered by user interactions and the current URL.

Coach relies on hover + fine-pointer interactions and is skipped on touch-only devices.

Installation

Via <script> (CDN)

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

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

Via npm

npm install @meltingspot/coach

import { Coach } from '@meltingspot/coach';
import '@meltingspot/coach/stylesheet.css';

Authentication (authToken)

authToken is the current user's MeltingSpot SSO token. Provide it to re-authenticate the user at start; omit it to rely on an existing authenticated session. Activate SSO on your spot to obtain these tokens.

Quick start

// Start the coach for your spot.
await Coach.start({
  spotId: 'YOUR_SPOT_ID',
  authToken: 'CURRENT_USER_SSO_TOKEN',
});

// Stop and tear down the coach.
await Coach.stop();

When loaded via the CDN <script>, start the coach once the DOM is ready:

<script>
  window.addEventListener('DOMContentLoaded', function () {
    window.MeltingSpot.Coach.start({
      spotId: 'YOUR_SPOT_ID',
      authToken: 'CURRENT_USER_SSO_TOKEN',
    });
  });
</script>

Start options

| Option | Type | Required | Default | Description | | --------------------- | ------------------------------- | -------- | ----------------------------------------------- | ---------------------------------------------------------------------- | | spotId | string | Yes | n/a | Target spot id. | | authToken | string | No | none (reuse existing session) | Current user's MeltingSpot SSO token. | | autoRefresh | AutoRefreshOptions | No | see AutoRefreshOptions | Fine-tune which browser events trigger a re-evaluation. | | initialPosition | 'left' \| 'center' \| 'right' | No | 'center' | Initial coach window position. | | lang | string | No | member's language (English fallback) | Member language driving the built-in translations. | | translations | CoachTranslationsOverrides | No | built-in strings | Override built-in conversation UI strings (see below). | | url | string | No | current location | Forces the URL evaluated at startup. | | conversationEnabled | boolean | No | server-driven, else false | Client-side fallback used when the server config fetch fails at start. | | debug | boolean | No | false | Verbose logging. |

AutoRefreshOptions

Controls which browser signals make the coach re-evaluate playbooks. All fields are optional booleans:

| Field | Default | Description | | ----------------- | ------- | ---------------------------------------------------- | | onHistoryChange | true | Re-evaluate on pushState / replaceState. | | onPopState | true | Re-evaluate on back/forward navigation (popstate). | | onLoad | true | Re-evaluate on the load event. | | onHashChange | true | Re-evaluate on hashchange. | | onDomMutation | false | Re-evaluate on relevant DOM mutations. |

CoachTranslationsOverrides

Override the built-in UI strings (merged on top of the language resolved from lang). Every field is optional:

await Coach.start({
  spotId: 'YOUR_SPOT_ID',
  lang: 'fr',
  translations: {
    conversation: {
      newConversation: 'Nouvelle conversation',
      inputPlaceholder: 'Posez votre question…',
      welcomeMessage: 'Bonjour 👋',
      agentThinking: 'Réflexion…',
      // backToConversation, later, errorFallback, expiredFallback also available
    },
    // mutedHand, autoDismiss groups are also overridable
  },
});

All groups are optional; any omitted string keeps its built-in translation.

| Group | Type | Default | Description | | -------------- | ----------------------------------- | ---------------- | -------------------------------------------- | | conversation | Partial<ConversationTranslations> | built-in strings | Conversation UI strings (input, welcome, …). | | mutedHand | Partial<MutedHandTranslations> | built-in strings | Muted-hand re-entry prompt strings. | | autoDismiss | Partial<AutoDismissTranslations> | built-in strings | Auto-dismiss accessibility strings. |

See the MeltingSpot helpdesk for the full integration guide.