@getcredify/credify-insurance-widget

v1.7.1

Published

14 days ago

Credify Insurance Widget - Embeddable React widget for insurance quotes

0High
0Medium
0Low

samc621

thewildzeno

Credify Insurance Widget

A React-based insurance quote widget that can be installed via npm package or embedded via script tag or iframe.

Installation

As an npm Package

npm install @getcredify/credify-insurance-widget

Peer Dependencies

This package requires React 18+ or React 19+ as a peer dependency:

npm install react@^18.0.0 react-dom@^18.0.0
# or
npm install react@^19.0.0 react-dom@^19.0.0

Note: The widget is compatible with React 18.x and 19.x. React is not bundled with the widget, so your application must provide it. The library build externalizes all React entry points (react, react-dom, react-dom/client, react/jsx-runtime), so the host must provide a single React/React-DOM (18.x or 19.x). The widget uses React 18+ APIs (like createRoot from react-dom/client), which are available in both React 18 and 19.

For Local Development

npm install

Development

Library Mode (Script Tag)

npm run dev

Iframe Mode

npm run dev:iframe

Building

Build both library and iframe versions:

npm run build

Build only library version:

npm run build:lib

Build only iframe version:

npm run build:iframe

Embedding Methods

Method 1: npm Package (Recommended)

Install and import the widget in your React application:

import { CredifyInsuranceWidget } from '@getcredify/credify-insurance-widget';

function App() {
  useEffect(() => {
    // Initialize the widget (styles are injected automatically)
    CredifyInsuranceWidget.init({ autoOpen: false });
  }, []);

  return (
    <div>
      <button onClick={() => CredifyInsuranceWidget.open()}>Open Widget</button>
      <button onClick={() => CredifyInsuranceWidget.close()}>Close Widget</button>
    </div>
  );
}

Note: The widget injects its own styles at runtime. You can optionally import @getcredify/credify-insurance-widget/widget.css if you prefer to load styles separately (e.g. for caching).

Method 2: Script Tag Embedding (UMD)

Include the widget as a script tag on your page. No separate CSS file is required—styles are injected when the script runs.

<!DOCTYPE html>
<html>
  <head>
    <script src="https://widget.getcredify.com/index.umd.js"></script>
    <!-- Also include React and ReactDOM if not already present -->
    <!-- For React 18: Use UMD builds -->
    <script src="https://unpkg.com/react@18/umd/react.production.min.js"></script>
    <script src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"></script>
    <!-- For React 19: Use ESM (no UMD builds available) -->
    <!-- <script type="module">
      import React from 'https://esm.sh/react@19';
      import ReactDOM from 'https://esm.sh/react-dom@19';
      window.React = React;
      window.ReactDOM = ReactDOM;
    </script> -->
  </head>
  <body>
    <button onclick="window.CredifyInsuranceWidget.open()">Open Widget</button>

    <script>
      // Initialize the widget
      window.CredifyInsuranceWidget.init({ autoOpen: false });

      // Open the widget
      function openWidget() {
        window.CredifyInsuranceWidget.open();
      }

      // Close the widget
      function closeWidget() {
        window.CredifyInsuranceWidget.close();
      }
    </script>
  </body>
</html>

See examples/umd.html for a complete example.

CDN Options:

The widget is available via CDN. We recommend using our CloudFront CDN:

<script src="https://widget.getcredify.com/index.umd.js"></script>

Alternatively, the package is also available via unpkg.com:

<script src="https://unpkg.com/@getcredify/credify-insurance-widget/dist/index.umd.js"></script>

Method 3: Iframe Embedding (Cross-Origin)

The widget can be embedded as an iframe on different origins. This is useful for:

Isolating the widget from your site's CSS/JavaScript
Serving the widget from a different domain
Better security and performance isolation

Step 1: Deploy the Widget

After building with npm run build:iframe, deploy the contents of dist/iframe/ to your server.

Note: The iframe HTML is available at @getcredify/credify-insurance-widget/iframe after installation, but typically you'll want to deploy it to your own server.

Step 2: Embed the Iframe

<!DOCTYPE html>
<html>
  <head>
    <title>My Page</title>
  </head>
  <body>
    <button id="open-btn">Open Widget</button>
    <button id="close-btn">Close Widget</button>

    <iframe
      id="widget-iframe"
      src="https://your-widget-domain.com/iframe.html"
      width="100%"
      height="700"
      style="border: none;"
      allow="clipboard-read; clipboard-write"
      sandbox="allow-scripts allow-same-origin allow-forms allow-popups allow-popups-to-escape-sandbox"
    ></iframe>

    <script>
      const iframe = document.getElementById('widget-iframe');

      // Open the widget
      document.getElementById('open-btn').addEventListener('click', () => {
        iframe.contentWindow.postMessage(
          {
            type: 'open',
            source: 'credify-insurance-widget'
          },
          'https://your-widget-domain.com'
        );
      });

      // Close the widget
      document.getElementById('close-btn').addEventListener('click', () => {
        iframe.contentWindow.postMessage(
          {
            type: 'close',
            source: 'credify-insurance-widget'
          },
          'https://your-widget-domain.com'
        );
      });

      // Listen for events from the widget
      window.addEventListener('message', (event) => {
        // Verify origin for security
        if (event.origin !== 'https://your-widget-domain.com') return;

        if (event.data?.source === 'credify-insurance-widget') {
          switch (event.data.type) {
            case 'ready':
              console.log('Widget is ready');
              break;
            case 'opened':
              console.log('Widget opened');
              break;
            case 'closed':
              console.log('Widget closed');
              break;
          }
        }
      });
    </script>
  </body>
</html>

See examples/iframe.html for a complete example.

Full Page Mode

The simplest way to integrate the widget is to embed it directly in your page and open it as a full-page modal overlay. This provides the best user experience as the widget gets the full screen space in the current window.

Step 1: Load the Widget

<!DOCTYPE html>
<html>
  <head>
    <title>My Page</title>
    <!-- Load React and ReactDOM (required peer dependencies) -->
    <!-- For React 18: Use UMD builds -->
    <!-- <script src="https://unpkg.com/react@18/umd/react.production.min.js"></script> -->
    <!-- <script src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"></script> -->

    <!-- For React 19: Use ESM (no UMD builds available) -->
    <script type="module">
      // Import React 19 as ESM modules - use exact same version for both
      import React from 'https://esm.sh/[email protected]';
      import ReactDOM from 'https://esm.sh/[email protected]';

      // Expose as globals for the UMD widget build
      window.React = React;
      window.ReactDOM = ReactDOM;

      // Load the widget script after React is available
      const script = document.createElement('script');
      script.src = 'https://widget.getcredify.com/index.umd.js';
      script.onload = () => {
        window.dispatchEvent(new Event('widget-loaded'));
      };
      document.head.appendChild(script);
    </script>
  </head>
  <body>
    <button id="open-btn">Get Insurance Quote</button>

    <script>
      window.addEventListener('DOMContentLoaded', () => {
        // Initialize the widget (don't auto-open)
        window.CredifyInsuranceWidget.init({ open: false });

        // Open the widget when button is clicked
        document.getElementById('open-btn').addEventListener('click', () => {
          window.CredifyInsuranceWidget.open();
        });
      });
    </script>
  </body>
</html>

The widget will open as a full-page modal overlay that covers the entire viewport. Users can close it by clicking the close button or pressing Escape.

Benefits of Full Page Mode:

✅ Full-page modal overlay - widget takes full screen space
✅ No iframe restrictions - full access to browser features
✅ Easier to implement - no postMessage API needed
✅ Better mobile experience - full screen on mobile devices
✅ Same origin - no cross-origin communication needed

See examples/fullpage.html for a complete example.

PostMessage API

When using iframe embedding, the widget communicates via the postMessage API.

Commands (Parent → Widget)

Send these messages to the widget:

{ type: 'open', source: 'credify-insurance-widget' } - Opens the widget
{ type: 'close', source: 'credify-insurance-widget' } - Closes the widget
{ type: 'init', source: 'credify-insurance-widget' } - Initializes the widget (sent automatically)

Events (Widget → Parent)

Listen for these events from the widget:

{ type: 'ready', source: 'credify-insurance-widget' } - Widget is ready
{ type: 'opened', source: 'credify-insurance-widget' } - Widget has opened
{ type: 'closed', source: 'credify-insurance-widget' } - Widget has closed

Server Configuration

When serving the widget for iframe embedding, ensure your server:

Allows iframe embedding - Do NOT set X-Frame-Options: DENY or X-Frame-Options: SAMEORIGIN headers. To allow embedding from specific origins, use Content Security Policy:
```
Content-Security-Policy: frame-ancestors 'self' https://example.com https://another-domain.com;
```

Sets CORS headers (if needed for API calls):

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization

Serves the iframe HTML from the dist/iframe/ directory after building

Security Considerations

Origin Verification: In production, always verify event.origin when receiving postMessage events to prevent XSS attacks
Specific Origins: Replace '*' with specific origins in postMessage calls for better security
HTTPS: Always serve the widget over HTTPS in production
CSP: Consider implementing Content Security Policy headers for additional protection

API Reference

Script Tag API

interface CredifyInsuranceWidgetAPI {
  init(options?: { autoOpen?: boolean }): void;
  open(): void;
  close(): void;
  destroy(): void;
}

init(options?) - Initialize the widget. Set autoOpen: true to open immediately.
open() - Open the widget
close() - Close the widget
destroy() - Remove the widget from the DOM

Examples

See the examples/ directory for complete working examples:

umd.html - Script tag embedding
iframe.html - Iframe embedding with postMessage communication
fullpage.html - Full page widget opened in a new window/tab