@getcredify/credify-insurance-widget
v1.51.0
Published
Credify Insurance Widget - Embeddable React widget for insurance quotes
Readme
Credify Insurance Widget
An embeddable insurance quote widget. Add it to your site with an npm package, a script tag, or an iframe.
Full guide: developer.getcredify.com/widget. Your partner ID and ready-to-paste snippets are in the partner portal under Integrations.
Installation
As an npm Package
npm install @getcredify/credify-insurance-widgetPeer Dependencies
The npm package needs React 18 or 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.0Note: The npm build does not bundle React, so your application must provide
it. All React entry points (react, react-dom, react-dom/client,
react/jsx-runtime) are external, so the host must provide a single React and
React DOM (18.x or 19.x). The script-tag build below bundles its own React.
Embedding Methods
Method 1: npm Package (Recommended)
Install and import the widget in your React application:
import { useEffect } from 'react';
import { CredifyInsuranceWidget } from '@getcredify/credify-insurance-widget';
function App() {
useEffect(() => {
// Styles are injected automatically
CredifyInsuranceWidget.init({
autoOpen: false,
partner: { id: 'cp_live_your_partner_id' }
});
}, []);
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. The script bundles its own React, so the page needs nothing else, and 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>
</head>
<body>
<button onclick="window.CredifyInsuranceWidget.open()">Get a Quote</button>
<script>
window.CredifyInsuranceWidget.init({
autoOpen: false,
partner: { id: 'cp_live_your_partner_id' }
});
</script>
</body>
</html>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 also run in an iframe, which isolates it from your site's CSS and JavaScript. Credify hosts the iframe page, so there is nothing to build or deploy:
https://widget.getcredify.com/iframe/iframe.htmlPut your partner ID on the iframe src as ?credify_partner=, and optionally a
placement label as &credify_sub= (see Labelling a placement).
?credify_product= works here too (see Choosing the flow).
You control the widget with postMessage:
<!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://widget.getcredify.com/iframe/iframe.html?credify_partner=cp_live_your_partner_id&credify_sub=homepage"
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 WIDGET_ORIGIN = 'https://widget.getcredify.com';
const iframe = document.getElementById('widget-iframe');
// Open the widget
document.getElementById('open-btn').addEventListener('click', () => {
iframe.contentWindow.postMessage({ type: 'open', source: 'credify-insurance-widget' }, WIDGET_ORIGIN);
});
// Close the widget
document.getElementById('close-btn').addEventListener('click', () => {
iframe.contentWindow.postMessage({ type: 'close', source: 'credify-insurance-widget' }, WIDGET_ORIGIN);
});
// Listen for events from the widget
window.addEventListener('message', (event) => {
// Only trust messages from the widget's origin
if (event.origin !== WIDGET_ORIGIN) 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>Full Page Mode
With the npm package or the script tag, the widget opens as a modal overlay that covers the full viewport, with the quote form in a centred panel. Visitors close it with the close button or Escape. There is no iframe, so no postMessage is needed.
For a page that exists only to collect quotes, pass autoOpen: true and the
widget opens as soon as the page loads:
<!DOCTYPE html>
<html>
<head>
<title>Get a Quote</title>
<script src="https://widget.getcredify.com/index.umd.js"></script>
</head>
<body>
<button onclick="window.CredifyInsuranceWidget.open()">Get Insurance Quote</button>
<script>
window.CredifyInsuranceWidget.init({
autoOpen: true,
partner: { id: 'cp_live_your_partner_id' }
});
</script>
</body>
</html>The button lets a visitor reopen the widget after closing it.
Mock Mode (Demo / Test Drive)
Mock mode lets you walk through the entire quote flow — postal code, every form stage, SMS verification, rate results, and bind — without entering real data or submitting a real quote. While active, every widget API call is answered from built-in sample data instead of hitting Credify's servers, so no SMS is sent and no quote is ever created.
Use it to demo or evaluate the widget on your own page before going live.
Enabling it
Mock mode is gated by an unguessable key, provided by the Credify team. It turns
on only when the page the widget runs in is loaded with a matching ?mock=<key>
query parameter — so where you add it depends on which embedding method (above) you
use:
npm Package, Script Tag (UMD), or Full Page Mode — the widget runs in your own page, so add
?mock=<key>to that page's address:https://your-site.com/insurance?mock=YOUR_KEY_FROM_CREDIFYIframe Embedding — the widget runs inside the iframe, so add
?mock=<key>to the iframe'ssrc:<iframe src="https://widget.getcredify.com/iframe/iframe.html?mock=YOUR_KEY_FROM_CREDIFY"></iframe>
Open and step through the widget exactly as a real user would. A small red
MOCK MODE badge appears in the bottom-left corner as a reminder that nothing is
being submitted. Remove the ?mock= parameter to return to the live flow.
Note: Without the matching key, mock mode stays completely off and the widget talks to the live API as usual — so the same embed code is safe to ship to production. The key only gates demo behaviour in the browser session that supplies it; it grants no access and carries no risk if shared.
Partner attribution
If you are a Credify partner, tell the widget who you are and the quotes it collects are credited to your firm:
<script src="https://widget.getcredify.com/index.umd.js"></script>
<script>
CredifyInsuranceWidget.init({
partner: { id: 'cp_live_your_partner_id' }
});
</script>Your partner ID is in the partner portal under Integrations, with this snippet already filled in. You do not create it — it exists as soon as your firm profile does, and it never changes.
In an iframe embed, put the same id on the iframe src instead:
?credify_partner=cp_live_your_partner_id (see
Method 3).
It is not a secret. It names your firm and authorizes nothing: holding it lets you say "credit Acme for this quote" and nothing else. It cannot submit an application, read anything, or act as you. So it belongs in your page source, and there is nothing to rotate.
Never put a secret key here. The sk_live_/sk_test_ keys are for
server-to-server calls to the Intake API, and anyone viewing your page could
read one pasted into this snippet. The widget refuses anything that is not a
cp_ id, but the safer habit is not to have the key near the browser at all.
Your logo and color
The same id also brands the widget. Set your logo and brand color on your Partner profile page in the partner portal (Settings → Profile → Open profile) and embeds carrying your id pick them up — there is nothing to add to the snippet.
Your logo appears above the quote form, and your brand color becomes the fill behind the buttons customers press. A color you have not set means Credify's own green, so an embed looks exactly as it does today until you choose otherwise.
Logos are PNG, JPEG or WebP up to 1 MB, re-encoded and served from
assets.getcredify.com. SVG is not accepted: it is a document that can carry
script, not just a picture.
Changes reach live embeds within about five minutes.
What does not change is the licence disclosure under the form, and the support number on it. Quotes are written by Credify Corporation, a licensed insurance agency, whoever referred the customer — so the widget carries your branding and Credify's licensing at the same time, which is what makes the co-branding truthful.
If the branding cannot be loaded the widget renders unbranded and the quote proceeds normally, for the same reason a malformed id does not stop one.
Labelling a placement
sub records which page or campaign produced the quote, and comes back in your
reporting. Different pages can carry different values with the same id:
CredifyInsuranceWidget.init({
partner: { id: 'cp_live_your_partner_id', sub: 'homepage-hero' }
});In an iframe embed, use &credify_sub=homepage-hero on the src.
Lowercased and reduced to letters, digits, - and _; capped at 100
characters.
If you get it wrong
A malformed id — a typo, or a secret key pasted in by mistake — is ignored with a console warning and the flow continues unattributed. A visitor never loses a quote because attribution was misconfigured, so check your browser console after wiring it up rather than assuming silence means success.
An id belonging to a partner who is no longer active stops attributing for the same reason: the quote is still created, it is simply credited to nobody.
Skipping questions you have already asked
If your page collects a ZIP, an email or a phone number of its own, hand them over and the flow starts on the first question the visitor has not seen:
CredifyInsuranceWidget.init({
partner: { id: 'cp_live_your_partner_id' },
prefill: { zip: '78701', email: '[email protected]', phone: '(512) 555-0134' }
});All three are optional and independently applied. phone is a US number,
formatted or not, with or without the +1. A value the flow cannot use — a
four-digit ZIP, something that is not an address — is dropped and that one
question is asked as usual, so a bad value costs the shortcut and never the
quote. A visitor resuming a saved quote is never overwritten: their own answers
win.
Choosing the flow
The widget quotes one product — Home, Auto, or Bundle — and it has to know
which before the first step renders: the product decides which stages exist, so
it is answered outside the form rather than inside it, exactly as the website's
/home-insurance and /auto-insurance routes do. The visitor is never asked
again during the flow.
Two ways to say it, in order of precedence:
1. A link parameter — ?credify_product=
https://partner.example.com/insurance?credify_product=autoThe widget picks up the product, opens straight into that flow, and strips the parameter from the address bar. Use it for campaign links, emails, and ads that should land in a specific funnel. Accepted values (case-insensitive):
| Product | Values |
| --- | --- |
| Home | home, home-insurance, homeowners |
| Auto | auto, auto-insurance, car, vehicle |
| Bundle | bundle, bundle-insurance |
An unrecognised value is ignored, and the visitor gets the page's own product.
2. The host's option — init({ product })
CredifyInsuranceWidget.init({ product: 'Auto' });What this page quotes by default, for an embed that sits on a product page. A
?credify_product= link overrides it for the visit that carries it.
With neither, the widget quotes Home.
Iframe embeds can use either the ?credify_product= parameter on the iframe
src or the product field on the init message; the parameter wins, and
unlike the script-tag embed it does not open the modal — visibility stays with
the parent's open message.
PostMessage API
When using iframe embedding, the widget communicates via the postMessage API.
Send commands to, and accept events only from, https://widget.getcredify.com.
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' }- Optional. Acceptsproduct: 'Home' | 'Auto' | 'Bundle'(see Choosing the flow); the widget replies withready
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
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, submissionFailed,
and data is the matching payload documented under Events. Example:
window.addEventListener('message', (e) => {
if (e.origin !== 'https://widget.getcredify.com') return;
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 });
}
});Security Considerations
- Origin Verification: When embedding the iframe, check
event.origin === 'https://widget.getcredify.com'before acting on a message, and pass that origin as the target of your ownpostMessagecalls - HTTPS: Serve the page that embeds the widget over HTTPS
- Secret keys: Only the public
cp_live_…partner ID belongs in page source; never ansk_key
API Reference
Script Tag API
interface CredifyInsuranceWidgetAPI {
init(options?: {
autoOpen?: boolean;
product?: 'Home' | 'Auto' | 'Bundle';
partner?: { id: string; sub?: string };
prefill?: { zip?: string; email?: string; phone?: string };
}): void;
open(): void;
close(): void;
destroy(): void;
on<E extends WidgetEventName>(event: E, callback: (data: WidgetEventMap[E], meta: WidgetEventMeta) => void): void;
off<E extends WidgetEventName>(event: E, callback: (data: WidgetEventMap[E], meta: WidgetEventMeta) => void): void;
}init(options?)- Initialize the widget. SetautoOpen: trueto open immediately,productto say which flow the page quotes (see Choosing the flow),partnerto credit your firm (see Partner attribution), andprefillto skip questions your page already asked (see Skipping questions).open()- Open the widgetclose()- Close the widgetdestroy()- Remove the widget from the DOMon(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.
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 |
| submissionFailed | { reason: 'submission' \| 'timeout' \| 'network' } | A quote submission fails (worker error, timeout, or repeated network errors) |
Every callback also receives meta: { quoteId, timestamp }, where quoteId
is null until the quote exists. The event names and payload types
(WidgetEventName, WidgetEventMap, WidgetEventMeta, 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)), because the in-iframe emitter is not reachable from the host page.
