@getcredify/credify-insurance-widget

v1.1.0

Published

9 days ago

Credify Insurance Widget - Embeddable React widget for insurance quotes

Downloads

507

0High
0Medium
0Low

samc621

thewildzeno

Credify Insurance Widget

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

Installation

As an npm Package

npm install @getcredify/credify-insurance-widget

Peer Dependencies

This package requires React 19+ as a peer dependency:

npm install react@^19.0.0 react-dom@^19.0.0

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';
import '@getcredify/credify-insurance-widget/widget.css';

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

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

Note: Make sure to import the CSS file for proper styling.

Method 2: Script Tag Embedding (UMD)

Include the widget as a script tag on your page:

<!DOCTYPE html>
<html>
  <head>
    <script src="https://widget.getcredify.com/index.umd.js"></script>
    <!-- Also include React and ReactDOM if not already present -->
    <script src="https://unpkg.com/react@19/umd/react.production.min.js"></script>
    <script src="https://unpkg.com/react-dom@19/umd/react-dom.production.min.js"></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) -->
    <!-- Note: React 19 doesn't have UMD builds, so we use ESM and expose as globals -->
    <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>
    <link rel="stylesheet" href="https://widget.getcredify.com/credify-insurance-widget.css" />
  </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, pressing Escape, or clicking the backdrop.

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