@getcredify/credify-insurance-widget 1.24.0 → 1.27.0

package/README.md

@@ -318,6 +318,23 @@ Listen for these events from the widget:
 - `{ type: 'opened', source: 'credify-insurance-widget' }` - Widget has opened
 - `{ type: 'closed', source: 'credify-insurance-widget' }` - Widget has closed
 
+Funnel/analytics events are also forwarded with `type: 'event'`:
+
+- `{ type: 'event', source: 'credify-insurance-widget', event, data }`
+
+where `event` is one of `widgetOpened`, `widgetClosed`, `stageViewed`,
+`stageCompleted`, `flowCompleted`, `ratesViewed`, `ratesBack`, and `data` is the
+matching payload documented under [Events](#events). Example:
+
+```javascript
+window.addEventListener('message', (e) => {
+  if (e.data?.source !== 'credify-insurance-widget' || e.data.type !== 'event') return;
+  if (e.data.event === 'stageCompleted') {
+    analytics.track('insurance_step', { step: e.data.data.stageKey });
+  }
+});
+```
+
 ## Server Configuration
 
 When serving the widget for iframe embedding, ensure your server:
@@ -355,6 +372,8 @@ interface CredifyInsuranceWidgetAPI {
   open(): void;
   close(): void;
   destroy(): void;
+  on<E extends WidgetEventName>(event: E, callback: (data: WidgetEventMap[E]) => void): void;
+  off<E extends WidgetEventName>(event: E, callback: (data: WidgetEventMap[E]) => void): void;
 }
 ```
 
@@ -362,6 +381,39 @@ interface CredifyInsuranceWidgetAPI {
 - `open()` - Open the widget
 - `close()` - Close the widget
 - `destroy()` - Remove the widget from the DOM
+- `on(event, callback)` - Subscribe to a widget event (see below)
+- `off(event, callback)` - Unsubscribe a previously registered callback
+
+### Events
+
+Subscribe to widget lifecycle and funnel events to forward them to your own
+analytics (Segment, GTM, Amplitude, etc.). Register listeners **before** calling
+`init`/`open`, since `widgetOpened` fires as the widget mounts.
+
+```javascript
+CredifyInsuranceWidget.on('stageCompleted', (data) => {
+  analytics.track('insurance_step', { step: data.stageKey });
+});
+```
+
+| Event            | Payload                                                          | Fires when                                      |
+| ---------------- | --------------------------------------------------------------- | ----------------------------------------------- |
+| `widgetOpened`   | _none_                                                          | The widget overlay opens                        |
+| `widgetClosed`   | _none_                                                          | The widget overlay closes                       |
+| `stageViewed`    | `{ stageKey, stageTitle, stepIndex, totalSteps }`               | A form stage becomes visible                    |
+| `stageCompleted` | `{ stageKey, stageTitle, stepIndex, totalSteps }`               | A form stage is successfully completed          |
+| `flowCompleted`  | _none_                                                          | All stages are done and rate generation starts  |
+| `ratesViewed`    | `{ rateCount: number }`                                         | The rates screen is shown                       |
+| `ratesBack`      | _none_                                                          | The user navigates back from the rates screen   |
+
+The event names and payload types (`WidgetEventName`, `WidgetEventMap`,
+`StageEventData`) are exported from the package for TypeScript consumers. Host
+callbacks are invoked in isolation — a throwing callback is reported and never
+breaks the widget.
+
+> **Iframe embedding:** the same events are delivered to the parent window over
+> postMessage instead (see [Events (Widget → Parent)](#events-widget--parent)),
+> because the in-iframe emitter is not reachable from the host page.
 
 ## Examples