Embed the widget

You embed the widget entirely from the browser. A frontend key (bzy_fk_*) creates the session and starts the widget.

Before you start

You need:

• A frontend key from Breezy (bzy_fk_test_… for testing, bzy_fk_live_… for production).
• Your page’s origin (for example https://www.example.com) added to your origin allow-list. Requests from other origins are rejected with origin_not_allowed.

Note

A frontend key is visible in your page source. It can only create sessions, and its burst and daily limits cap to avoid overuse.

Install

npm install @breezy-technologies/breezy-js

Or load it from the CDN, which exposes the global Breezy:

<script src="https://js.staging.partner.breezy.com/v1/breezy.js"></script>

Mount the widget

Add a container where the widget should appear on your website:

<div id="breezy-property"></div>

To initialise Breezy Widget - create a session with your frontend key and mount the widget. loadBreezy needs your key and createWidget needs fetchClientSecret; both are required:

import { loadBreezy } from '@breezy-technologies/breezy-js';

const FRONTEND_KEY = 'bzy_fk_test_…';

const breezy = await loadBreezy(FRONTEND_KEY);
const widget = breezy.createWidget({
  variant: 'compact', // 'card' | 'compact' | 'floating'
  fetchClientSecret: async () => {
    const res = await fetch('https://api.staging.partner.breezy.com/v1/embed/sessions', {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${FRONTEND_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        widget_type: ['underbuilt'],
        embed_origin: window.location.origin,
      }),
    });
    return (await res.json()).client_secret;
  },
});
widget.on('error', (err) => console.warn(err.code));
await widget.mount('#breezy-property');

POST /v1/embed/sessions returns a short-lived client_secret, which the widget uses for its data requests.

Choose a variant

variant sets the layout of the widget. It is optional, and the widget uses compact when you leave it out.

Value	Layout
compact	Default. A compact summary card with the address, the key figure, and a short report link.
card	A larger card that adds a row of detail tiles below the summary.
floating	A floating card.

The variant only changes how the widget looks. The data it shows comes from the session’s widget_type.

Choose the data

The data modules (underbuilt, roi) available to you are set by Breezy when your account is configured. You then choose which of them each widget shows.

For example, if both are enabled for your account, you can still ask for only underbuilt:

body: JSON.stringify({
  widget_type: ['underbuilt'], // roi is enabled for you, but this widget won't show it
  embed_origin: window.location.origin,
}),

Every session needs at least one module, so widget_type can’t be empty. If you request both, the widget shows them as tabs. If you request a module that isn’t enabled for your account, the request fails with a request_invalid error. Contact Breezy to enable more modules.

Open on a specific address

By default the widget opens on an address search bar. If your page already knows the address, pass it in property and the widget opens straight on that property.

Copy this into your page. The <script> goes at the end of <body>, after the container <div>:

<div id="breezy-property"></div>

<script src="https://js.staging.partner.breezy.com/v1/breezy.js"></script>
<script type="module">
  const FRONTEND_KEY = 'bzy_fk_test_…';

  // 1. The address to show. Use null to open the search bar instead.
  let address = '123 Main St, Austin, TX 78701';

  const breezy = await Breezy.loadBreezy(FRONTEND_KEY);

  const widget = breezy.createWidget({
    variant: 'compact',
    fetchClientSecret: async () => {
      const property = address ? { address } : undefined;

      const res = await fetch('https://api.staging.partner.breezy.com/v1/embed/sessions', {
        method: 'POST',
        headers: {
          Authorization: `Bearer ${FRONTEND_KEY}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({
          widget_type: ['underbuilt'],
          embed_origin: window.location.origin,
          property,
        }),
      });
      return (await res.json()).client_secret;
    },
  });

  // 2. Show the widget.
  await widget.mount('#breezy-property');
</script>

The address can be hard-coded, come from your page data, or be read from the URL (new URLSearchParams(location.search).get('address')).

Session options

Body of POST /v1/embed/sessions. Required fields are marked.

widget_typestring[]required

Which data the session shows: ["underbuilt"], ["roi"], or both. A session needs at least one module, and each module can appear only once. Breezy decides which modules are enabled for your account, so every module you request must be one of them. You can request all of them or only some.

embed_originstringrequired

The origin of the page hosting the widget, for example https://www.example.com. Must be on your allow-list.

propertyobject

Open the widget on a specific property with { "address": "123 Main St, Austin, TX 78701" }. Leave it off to open the address search. To pass an address from your own page, see Open on a specific address.

Content Security Policy

If your page sets a CSP, allow the Breezy hosts:

script-src https://js.staging.partner.breezy.com; frame-src https://widget.staging.partner.breezy.com; connect-src https://api.staging.partner.breezy.com