Notifizz Widget Bridge Reference

The Notifizz widget exposes a programmatic command/event surface — BRIDGE_COMMANDS for sending instructions to the widget, BRIDGE_EVENTS for listening to its state. The three frontend SDKs (@notifizz/react, @notifizz/angular, @notifizz/vanilla) all wrap this same surface; this page documents it directly so you can integrate the widget from any runtime.

TL;DR

window.notifizz(command, ...args) — invoke a bridge command.
window.addEventListener("notifizz:ready", cb) — fires once when the widget is loaded and authenticated.
window.addEventListener("notifizz:state", cb) — fires on every state change with event.detail: NotifizzState.
The contract lives in sdk/shared/contract.ts — single source of truth for both the widget and every SDK.

Public commands

BRIDGE_COMMANDS are the public, supported instructions. They’re the same across React, Angular, and Vanilla.

Command	Args	Description
`authenticateWithFirebase`	`{ apiKey, token, ...userFields? }`	Authenticate the widget session with a Firebase ID token.
`authenticateWithBackendToken`	`{ apiKey, token, userId, userEmail, ...additional? }`	Authenticate with an HMAC token minted server-side.
`authenticateWithNone`	`{ apiKey, userId, userEmail }`	Dev-only — no token verification.
`setPosition`	`'top-right' \| 'top-left' \| 'bottom-right' \| 'bottom-left'`	Move the bell to one of four screen corners.
`setNotificationCenterStyles`	`{ marginTop?: string }`	Adjust the notification-center dropdown placement.
`setBellStyles`	`{ marginRight?: string; marginLeft?: string }`	Adjust bell placement.
`toggle`	none	Toggle the dropdown open/closed.
`open`	none	Open the dropdown.
`close`	none	Close the dropdown.
`getState`	`(state: NotifizzState) => void`	Read the current state synchronously via callback.
`webpushOptIn`	none	Trigger the browser’s web push permission prompt + subscription. Call from a user gesture; gate on `state.webpushStatus === "ready"`.
`webpushOptOut`	none	Drop the browser’s push subscription and revoke it server-side.

// Drive the widget directly from any runtime
window.notifizz("setPosition", "top-right");
window.notifizz("toggle");
window.notifizz("getState", (state) => console.log(state.unreadCount));

A few internal commands (e.g. setBellIcon, setRoundedButton) live in a separate internal registry and are not part of BRIDGE_COMMANDS. They’re used by the SDK packages and may change without notice — don’t call them from your code.

Public events

BRIDGE_EVENTS are dispatched on window:

Event	Payload (`event.detail`)	Description
`notifizz:ready`	none	Fires once when the widget is loaded and authenticated. After this, `state.isReady === true`.
`notifizz:state`	`NotifizzState`	Fires on every state change. Subscribe to keep your UI in sync.

window.addEventListener("notifizz:ready", () => {
  console.log("widget ready");
});

window.addEventListener("notifizz:state", (e) => {
  const state = e.detail; // NotifizzState
  document.title = state.unreadCount > 0
    ? `(${state.unreadCount}) My App`
    : "My App";
});

`NotifizzState`

The state object delivered through notifizz:state and via the getState callback:

Property	Type	Description
`isReady`	`boolean`	`true` once the widget has loaded and authenticated.
`isOpen`	`boolean`	`true` when the dropdown is open.
`unreadCount`	`number`	Current unread notification count.
`lastUpdated`	`number`	Timestamp (ms) of the last state change.
`hasError`	`boolean?`	`true` if the widget hit an auth or network error.
`errorCode`	`string?`	Error identifier when `hasError` is `true`.
`webpushStatus`	`WebPushStatus?`	Web push opt-in status: `unavailable \| unsupported \| ready \| subscribed \| denied`. Appears once the widget has booted web push for the authenticated user.

The first four (STATE_FIELDS in the contract) are always present; hasError / errorCode and webpushStatus appear only once the widget enters an error state or boots web push, respectively.

Web push opt-in

The web push channel rides this same bridge, so you can offer the browser opt-in from your own button — no notification-center bell required. Two commands drive it; the status flows back through notifizz:state like any other field:

// Gate a button on the reactive status, then opt in on click.
window.addEventListener("notifizz:state", (e) => {
  // 'ready' = configured + verified, user hasn't decided → show/enable the button
  enableBtn.disabled = e.detail.webpushStatus !== "ready";
});

enableBtn.addEventListener("click", () => window.notifizz("webpushOptIn"));

webpushStatus starts unavailable and settles to ready once the environment has a key and the service worker is verified on your origin. Only ever call webpushOptIn from a real user gesture — browsers ignore a permission request that isn’t tied to a click. The framework SDKs wrap this as useNotifizz().webpush (React), NotifizzService.webpushStatus$ / .webpushOptIn() (Angular) and createNotifizz().webpushOptIn() (Vanilla); see the web push overview.

Lifecycle ordering

A typical session flows like this:

Always wait for notifizz:ready (or check state.isReady) before sending commands like toggle / open / close. Commands sent before ready are dropped silently — the React/Angular/Vanilla SDKs already gate on this; if you build your own integration, do the same.

Building your own integration

If you need a framework Notifizz doesn’t ship a SDK for (Vue 3 with composables, Solid, Svelte 5, …), the bridge is enough. Minimal recipe:

Inject the widget script (https://widget.notifizz.com/v1/widget.js) — use a <script> tag or your framework’s lifecycle hook.
Wait until typeof window.notifizz === "function".
Call window.notifizz("authenticateWith…", options) with your auth fields.
Listen for notifizz:ready to know when the widget is live.
Listen for notifizz:state to drive any UI you build around the widget.
Call window.notifizz("toggle" | "open" | "close") from your own UI elements.

The vanilla SDK (sdk/front-end/notifizz-vanilla) is a clean reference implementation — about 200 lines of glue around this exact protocol.

FAQ

Open the panel from a button — how?

Call window.notifizz("toggle") (or "open") from your click handler. If you’re using a framework SDK, prefer its idiomatic API (useNotifizz().toggle in React, NotifizzService.toggle() in Angular, notifizz.toggle() in Vanilla) — they all delegate to the same bridge command.

Read unread count without rendering the default bell.

Listen for notifizz:state and read state.unreadCount. Hide the default bell with CSS or by passing a custom render in your SDK (renderBell in React, #customBellIcon in Angular, setBellElement(el) in Vanilla).

`getState` returns `isReady: false` immediately after script load.

Expected — authentication is async. Call getState from inside notifizz:ready, or wait for the first notifizz:state event whose detail.isReady === true.

Command before `notifizz:ready` — what happens?

Dropped silently. The widget queues authenticateWith… calls but not toggle / open / close. Always gate your commands on state.isReady to avoid surprises.

Are `setBellIcon` and `setRoundedButton` supported?

No — those are internal commands used by the SDK packages and not part of BRIDGE_COMMANDS. They may change without notice. If you need a custom bell, use the renderBell (React), content-projection (Angular), or setBellElement(el) (Vanilla) APIs — those go through the supported public surface.

Multiple widgets on the same page — supported?

No, the widget is a singleton bound to window.notifizz. To switch users, destroy the current instance (via your SDK’s destroy() method) and re-mount with new auth. Two simultaneous identities aren’t supported today.

Notification Center overview

Lifecycle, state model, custom bell, headless mode.

React SDK

Idiomatic React wrapper around the bridge.

Vanilla JS SDK

Reference implementation of a bridge consumer.

Web push

The webpushOptIn / webpushOptOut commands and the opt-in-from-your-own-UI flow.

Authentication overview

The four widget auth modes and when to pick each.

Get started

Concepts

Use cases

SDKs

AI & MCP

Environments

Plans & usage

Monitor delivery

Glossary

Notifizz Widget Bridge Reference

Widget bridge reference

TL;DR

Public commands

Public events

`NotifizzState`

Web push opt-in

Lifecycle ordering

Building your own integration

FAQ

See also

Notification Center overview

React SDK

Vanilla JS SDK

Web push

Authentication overview

​Widget bridge reference

​TL;DR

​Public commands

​Public events

​NotifizzState

​Web push opt-in

​Lifecycle ordering

​Building your own integration

​FAQ

​See also

Notification Center overview

React SDK

Vanilla JS SDK

Web push

Authentication overview

Widget bridge reference

TL;DR

Public commands

Public events

`NotifizzState`

Web push opt-in

Lifecycle ordering

Building your own integration

FAQ

See also