SDK Reference

The JavaScript SDK provides programmatic control over widget initialization, theming, prefill, modal mode, and event handling.

Installation

Script tag (CDN)

<script src="https://cdn.benefithub.com/widget/v1/widget.js"></script>

<!-- The SDK exposes window.BHWidget -->
<script>
  const widget = BHWidget.init({
    key: 'YOUR_KEY',
    type: 'auto',
    baseUrl: 'https://widget.benefithub.insure',
  });
</script>

npm / pnpm (coming soon)

The @benefithub/insurance-widget npm package is not yet published. Use the CDN script tag above in the meantime.

BHWidget.init(config)

Creates and inserts the widget. Returns a BHWidgetInstance for later control. All config properties are flat (not nested):

const widget = BHWidget.init({
  key: 'wk_abc123',
  type: 'auto',
  container: '#my-container',
  mode: 'embedded',
  baseUrl: 'https://widget.benefithub.insure',
  agentId: 'agent_456',

  // Theme — flat properties, not a nested object
  'color-primary': '#1a365d',
  'color-accent': '#3182ce',
  'color-btn': '#2563eb',
  'color-btn-text': '#ffffff',
  'border-radius': '12px',

  // Prefill — flat properties, not a nested object
  firstName: 'Jane',
  lastName: 'Doe',
  email: 'jane@example.com',
  zip: '90210',

  // Callbacks
  onReady: () => console.log('Ready'),
  onQuoteResults: (count) => console.log(count + ' quotes'),
  onOpen: () => console.log('Modal opened'),
  onClose: () => console.log('Modal closed'),
});

Config Properties

Theme Properties

Theme values are passed as flat config properties, not a nested object. Both short and long aliases are accepted:

Prefill Properties

Prefill values are passed as flat config properties. PII is sent securely via postMessage after the iframe loads — never in the URL.

Event Callbacks

BHWidgetInstance

Returned by BHWidget.init().

Static Methods

Modal Mode Example

<button id="quote-btn">Get Insurance Quote</button>
<div id="bh-insurance-widget"></div>

<script src="https://cdn.benefithub.com/widget/v1/widget.js"></script>
<script>
  const widget = BHWidget.init({
    key: 'wk_abc123',
    type: 'auto',
    mode: 'modal',
    baseUrl: 'https://widget.benefithub.insure',
    onOpen: () => console.log('Modal opened'),
    onClose: () => console.log('Modal closed'),
  });

  // Open on button click
  document.getElementById('quote-btn')
    .addEventListener('click', () => widget.open());

  // Also dispatches CustomEvents you can listen to:
  window.addEventListener('bh:modal-open', () => {
    analytics.track('insurance_modal_opened');
  });
</script>

Full Embedded Example

<div id="insurance-widget"></div>

<script src="https://cdn.benefithub.com/widget/v1/widget.js"></script>
<script>
  const widget = BHWidget.init({
    key: 'wk_abc123',
    type: 'auto',
    container: '#insurance-widget',
    baseUrl: 'https://widget.benefithub.insure',
    mode: 'embedded',
    agentId: 'agent_456',
    logoUrl: 'https://example.com/logo.png',

    // Theme colors (flat — not nested)
    'color-primary': '#1a365d',
    'color-accent': '#3182ce',
    'color-btn': '#2563eb',
    'color-btn-text': '#ffffff',
    'border-radius': '12px',

    // Prefill (flat — not nested)
    firstName: 'Jane',
    lastName: 'Doe',
    email: 'jane@example.com',
    phone: '5551234567',
    zip: '90210',

    onReady: () => {
      console.log('Widget ready');
    },
    onStep: (step, name) => {
      analytics.track('insurance_step', { step, name });
    },
    onQuoteResults: (count) => {
      analytics.track('insurance_quotes', { count });
    },
    onError: (msg) => {
      console.error('Widget error:', msg);
    },
  });

  // Clean up when navigating away (SPA)
  window.addEventListener('beforeunload', () => widget.destroy());
</script>