Documentation
Start with the widget snippet, then connect subscribers, tags, events, API calls, and delivery workflows.
Welcome to the Ozibus Broadcast documentation. This guide helps you add the widget, collect subscribers, identify users, and send updates safely.
Make sure your Broadcast workspace is active and your public widget key is available in the dashboard.
Ozibus Broadcast is the customer update layer for merchant sites and apps. It allows you to:
web_push for browser/device notifications and in_app for updates shown inside the embedded widget or app surfaceChoose the integration method that works best for your application.
Add our JavaScript SDK to your HTML:
<script>
(function(w,d,s,o,f,js,fjs) {
w['OzibusBroadcastObject']=o;w[o]=w[o]||function(){
(w[o].q=w[o].q||[]).push(arguments);
};
js=d.createElement(s),fjs=d.getElementsByTagName(s)[0];
js.id=o;js.src=f;js.async=1;fjs.parentNode.insertBefore(js,fjs);
}(window,document,'script','ozb','https://broadcast.ozibus.com.au/embed/js/embed.js'));
ozb('init', 'YOUR_PUBLIC_KEY');
</script>
The same install snippet supports both web_push subscriptions and in_app update display. Web push requires browser permission and service-worker support; in-app updates are shown through the embedded Broadcast widget or your app surface.
Install our React package:
npm install @ozibus/broadcast-reactThen initialize it in your app:
import { OzibusBroadcastProvider } from '@ozibus/broadcast-react';
function App() {
return (
<OzibusBroadcastProvider publicKey="YOUR_PUBLIC_KEY">
{/* Your app components */}
</OzibusBroadcastProvider>
);
}
Ozibus Broadcast has two widget usages. You can use either one on its own, or use both together on the same merchant site.
| Widget usage | What it does | Best for |
|---|---|---|
| Subscription widget | Prompts visitors to opt in for web_push notifications and stores the browser subscription. |
Growing a push audience from storefront, app, checkout, or account pages. |
| Recent updates widget | Opens a branded updates panel for in_app announcements, changelogs, and unread counts. |
Showing customers what changed without asking for browser notification permission. |
web_pushUse the embed script when you want visitors to subscribe to browser push notifications. Automatic prompting can be enabled from the script tag, but explicit click-based prompting is usually better for mobile and browser compatibility.
<button type="button" id="enableBroadcastPush">Enable updates</button>
<script src="https://broadcast.ozibus.com.au/embed/js/embed.js"
data-public-key="YOUR_PUBLIC_KEY"
data-auto-prompt="false"
async></script>
<script>
document.getElementById('enableBroadcastPush').addEventListener('click', function () {
BroadcastPush.identify('CUSTOMER_ID', {
tags: ['returning_customer', 'promo_opt_in']
});
BroadcastPush.requestSubscribe({
user_id: 'CUSTOMER_ID',
tags: ['returning_customer', 'promo_opt_in']
});
});
</script>Call BroadcastPush.requestSubscribe() from a user action such as a button click. Mobile browsers and some desktop browsers may block permission prompts that are not triggered by user intent.
in_appUse the launcher widget when you want customers to open recent updates, read broadcast details, and see unread counts. This is the public-facing widget for in_app update discovery.
<button id="ozibusBroadcastLauncher" type="button">
What's New
<span data-oz-notification-count hidden>0</span>
</button>
<script>
window.Ozibus = {
selector: '#ozibusBroadcastLauncher',
public_key: 'YOUR_PUBLIC_KEY',
limit: 5,
target: 'all',
loading: {
enabled: true,
text: 'Loading updates...',
icon: 'fa-solid fa-spinner',
showText: true,
showIcon: false
},
theme: {
primary: '#2563eb',
badge: '#dc2626',
background: '#ffffff',
text: '#0f172a',
mutedText: '#64748b',
unreadBackground: '#eff6ff'
},
callbacks: {
onWidgetReady: function (widget) {
var unseen = Number(widget.getUnseenCount ? widget.getUnseenCount() : 0) || 0;
var badge = document.querySelector('[data-oz-notification-count]');
if (badge) {
badge.textContent = unseen > 99 ? '99+' : String(unseen);
badge.hidden = unseen <= 0;
}
},
onShowWidget: function () {},
onHideWidget: function () {}
}
};
</script>
<script src="https://cdn.ozibus.com.au/broadcast.widget.js" async></script>Use the subscription widget to build the web_push audience, and use the recent updates widget to keep in_app updates visible to visitors who are already on the site.
Ozibus Broadcast provides API access for broadcast, audience, delivery, and webhook workflows.
All API requests must include your API key in the Authorization header:
Authorization: Bearer YOUR_API_KEYUse the channels array to choose where a broadcast is delivered. The two core Broadcast channels are:
| Channel | Purpose | Typical Requirement |
|---|---|---|
| web_push | Browser notifications sent to subscribed devices, even when the merchant site is not open. | Verified domain, service worker, browser permission, and a saved push subscription. |
| in_app | Updates shown inside the embedded recent-updates widget or a signed app surface. | Installed widget or authenticated app context with the correct public key. |
Create and manage broadcast messages through our API.
POST /api/v1/broadcasts
Content-Type: application/json
{
"title": "Weekend offer is live",
"content": "Shop the weekend offer before it ends Sunday night.",
"channels": ["web_push", "in_app"],
"audience": { "tags": ["returning_customer"] },
"click_url": "https://example.com/offers/weekend",
"ttl": 259200,
"scheduled_for": "2026-05-17T10:00:00Z"
}
| Parameter | Type | Description |
|---|---|---|
| title required | string | The title of your broadcast |
| content required | string | The content of your broadcast (supports Markdown) |
| channels optional | array | Delivery channels. Use web_push for browser push and in_app for embedded or app-surface updates. Other configured channels can include slack and email. |
| click_url optional | string | Destination URL opened from a web_push notification or in-app update action. |
| ttl optional | integer | Web push time-to-live in seconds. Use it to prevent expired offers or alerts from being delivered late. |
| audience optional | object | Target audience filters |
| scheduled_for optional | string | ISO 8601 timestamp for scheduled delivery |
Broadcasts created via API are subject to the same rate limits as the dashboard. Ensure you stay within your plan's limits.
Follow these guidelines to maximize the effectiveness of your product communications:
Consider these factors when scheduling your broadcasts:
Version 2.0 introduces several breaking changes. Follow this guide to update your integration.
See how different audience filters affect who receives your broadcasts.
Select an audience segment to see how it affects your broadcast reach.
Practical examples of common Ozibus Broadcast implementations.
Announce a new feature to your premium users through both web push and in-app updates:
// Create a broadcast
const broadcast = await bh.createBroadcast({
title: "New Advanced Analytics Dashboard",
content: "We've completely redesigned our analytics dashboard with new visualization options and export capabilities.",
channels: ["web_push", "in_app"],
click_url: "https://example.com/analytics",
ttl: 86400,
audience: {
plan: "premium",
last_active: "30d"
},
metadata: {
feature_flag: "analytics_v2",
related_docs: "https://docs.example.com/analytics"
}
});
// Track engagement
bh.onBroadcastView(broadcast.id, (userId) => {
analytics.track('broadcast_viewed', {
broadcast_id: broadcast.id,
user_id: userId
});
});
Use the metadata field to attach additional context to your broadcasts that can be used for analytics or conditional logic in your application.
We offer tiered pricing based on the number of active users and features needed. See our pricing page for details.
Yes, our Starter plan is free for up to 1,000 users with basic features.
Our JavaScript SDK supports all modern browsers including Chrome, Firefox, Safari, and Edge. IE11 is not supported.
Call bh.identify(userId, traits) when a user logs in to your application. This enables audience targeting and personalization.