@superleapai/iframe-sdk

A powerful iframe SDK that enables bidirectional communication between embedded websites (in iframe) and parent CRM applications through global window custom events and postMessage API.

Features

• 🔄 Bidirectional Communication: Send and receive events between iframe and parent window
• 🌐 Cross-Origin Support: Works seamlessly with cross-origin iframes using postMessage fallback
• 🎯 Event-Driven Architecture: Simple event-based API for clean integration
• 🔧 Configurable: Customizable event prefixes and debug modes
• 📱 Toast Notifications: Built-in toast notification system
• ⏳ Loading States: Easy loading state management
• 🔍 TypeScript Support: Full TypeScript declarations included

Installation

npm install @superleapai/iframe-sdk

Quick Start

In your embedded website (iframe content):

// Import the SDK
import SuperleapCRM from '@superleapai/iframe-sdk';

// Or use via script tag
// <script src="path/to/index.js"></script>
// The SDK will be available as window.SuperleapCRM

// Show a success toast
SuperleapCRM.toast('Operation completed successfully!', 'success');

// Set loading state
SuperleapCRM.setIsLoading(true, 'Processing...');

// Close the form/modal
SuperleapCRM.closeForm({ reason: 'completed', data: { id: 123 } });

// Send custom events
SuperleapCRM.sendCustomEvent('userAction', { 
  action: 'click', 
  element: 'submit-button' 
});

// Listen for events from parent CRM
const cleanup = SuperleapCRM.listen('configUpdate', (detail) => {
  console.log('Received config update:', detail);
});

// Listen for all events
const cleanupAll = SuperleapCRM.listen((event) => {
  console.log('Received event:', event.type, event);
});

// Clean up listeners when done
cleanup();
cleanupAll();

In your parent CRM application:

// Listen for events from iframe
window.addEventListener('superleapCRM:closeForm', function(event) {
  console.log('Close form requested:', event.detail);
  // Handle close logic - hide modal, navigate away, etc.
});

window.addEventListener('superleapCRM:setLoading', function(event) {
  const { isLoading, message } = event.detail.payload;
  // Update your loading UI
  if (isLoading) {
    showLoadingSpinner(message);
  } else {
    hideLoadingSpinner();
  }
});

window.addEventListener('superleapCRM:showToast', function(event) {
  const { message, type, duration } = event.detail.payload;
  // Show toast in your CRM UI
  showToast(message, type, duration);
});

// For cross-origin iframes, also listen to postMessage
window.addEventListener('message', function(event) {
  if (event.data && event.data.type === 'SUPERLEAP_CRM_EVENT') {
    // Re-dispatch as custom event for consistent handling
    const customEvent = new CustomEvent(event.data.eventName, {
      detail: event.data.detail
    });
    window.dispatchEvent(customEvent);
  }
});

// Send events TO the iframe
window.dispatchEvent(new CustomEvent('superleapCRM:configUpdate', {
  detail: {
    payload: { theme: 'dark', language: 'en' }
  }
}));

API Reference

Methods

closeForm(data?: any): boolean

Sends an event to close the form/modal.

SuperleapCRM.closeForm({ reason: 'user_cancelled' });

setIsLoading(isLoading: boolean, message?: string): boolean

Sets the loading state in the parent CRM.

SuperleapCRM.setIsLoading(true, 'Saving data...');
SuperleapCRM.setIsLoading(false); // Hide loading

toast(message: string, type?: string, duration?: number): boolean

Shows a toast notification. Types: 'success', 'error', 'warning', 'info'.

SuperleapCRM.toast('Success!', 'success', 3000);
SuperleapCRM.toast('Something went wrong', 'error');

sendCustomEvent(eventType: string, data: any): boolean

Sends a custom event to the parent CRM.

SuperleapCRM.sendCustomEvent('formSubmit', { 
  formId: 'contact-form',
  data: { name: 'John', email: '[email protected]' }
});

listen(eventType: string, callback: Function): Function

Listens for specific events from the parent CRM. Returns cleanup function.

const cleanup = SuperleapCRM.listen('themeChange', (detail) => {
  document.body.className = detail.payload.theme;
});

// Clean up when done
cleanup();

listen(callback: Function): Function

Listens for all events from the parent CRM.

const cleanup = SuperleapCRM.listen((event) => {
  console.log(`Received ${event.type}:`, event);
});

configure(options: object): void

Configures the SDK.

SuperleapCRM.configure({
  debug: true, // Enable debug logging
  eventPrefix: 'myApp:' // Change event prefix
});

isInIframe(): boolean

Utility to check if running inside an iframe.

if (SuperleapCRM.isInIframe()) {
  console.log('Running in iframe');
}

version(): object

Returns version and API information.

console.log(SuperleapCRM.version());
// { version: "1.0.0", api: [...], eventPrefix: "superleapCRM:" }

Event Structure

All events follow this structure:

{
  detail: {
    payload: any, // Your event data
    timestamp: string, // ISO timestamp
    source: "embedded-site",
    isFromIframe: boolean
  }
}

Cross-Origin Support

The SDK automatically handles cross-origin scenarios:

1. Same-origin: Uses direct custom events on window.top
2. Cross-origin: Falls back to postMessage API
3. Parent CRM: Should listen for both custom events AND postMessage

TypeScript Support

The package includes full TypeScript declarations:

import SuperleapCRM, { SuperleapCRMConfig } from '@superleapai/iframe-sdk';

const config: SuperleapCRMConfig = {
  debug: true,
  eventPrefix: 'myApp:'
};

SuperleapCRM.configure(config);

Browser Support

• Modern browsers with ES6+ support
• IE11+ (with polyfills for CustomEvent if needed)
• All mobile browsers

License

ISC