Installing the Herald Widget

What the widget does

A small JS-powered popup that shows your changelog entries inside your product. Users open it from a trigger button. Unread releases show a badge or dot on the trigger so users know when there's something new.

The widget loads asynchronously, weighs in under 50ms on first paint, and doesn't block your app's load.

Installing

Add the Herald widget to your app with a single <script> tag. Drop it anywhere in your HTML where you'd want the widget trigger button to appear — typically inside your app's header, near the user menu, or wherever your "what's new" affordance belongs.

<script src="https://sendherald.com/widget.js" data-user-token="YOUR_USER_TOKEN" defer></script>

You'll find the exact <script> tag for your project in Settings → Widget → Install widget in the Herald dashboard. The page gives you the script tag pre-filled with your token, plus the public URL of your full hosted changelog page if you'd rather link to that.

That's the whole install. The widget renders the trigger button at the position you've configured (default: bottom-right), and clicking it opens the popup with your latest releases.

Widget customization

Project Settings → Widget → Customize widget exposes the following options, all with a live preview rendered alongside the form:

• Primary color — accent color used for the unread badge, links, and active states
• Background — popup panel background
• Text color — body text inside the popup
• Button color — color of the trigger button
• Font — typeface used inside the widget
• Border radius — corner rounding for the popup panel
• Position — where the trigger button anchors on the page (bottom-right, bottom-left, top-right, top-left, or attach to your own button)

Widget theming is available on Team+ plans.

Trigger button

The trigger button is the visible element your users click to open the widget. You can configure:

• Button text — label shown on the trigger (e.g., "What's new", "Updates")
• Display — whether the trigger shows the label, icon-only, or both
• Icon — choice of icon shown on the trigger
• Button radius — corner rounding for the trigger itself

If you'd prefer to attach the widget to an existing button in your app (e.g., a bell icon in your header), use the "attach to existing button" position option and supply a CSS selector.

The unread badge

The widget tracks which releases each visitor has seen and shows a dot or badge on the trigger when there are unread items. Two modes:

• Anonymous (all tiers) — read state is stored in the visitor's localStorage. Resets if they clear browser storage or switch devices.
• Per-user (Team+) — when you initialize the widget with a JWT-signed user identity, read state is stored server-side per user. It persists across devices and survives localStorage clearing.

Per-user mode is what powers the "read rate" metric in the analytics dashboard — without it, we can't distinguish "100 unique users read this once" from "1 user read this 100 times."

JWT authentication for private views (Team+)

On Team+ plans, you can sign a JWT containing your user's ID and group memberships from your backend, and pass it to the widget at init time. This unlocks:

• Per-user read tracking (cross-device persistence)
• Group-based release targeting — beta users see beta release items, enterprise customers see enterprise-specific notes
• Private changelog views — your gated changelog content is only visible to authenticated users

Your project's JWT signing secret lives in Settings → API in the Herald dashboard. See Audience Segmentation for the JWT payload format.

Live preview while configuring

The customize-widget form in Settings → Widget includes a live preview that updates as you change settings — including a simulated unread badge so you can see how it looks against your color choices. Save once you're happy. Changes take effect on the live widget within a few minutes (the widget script caches briefly on the CDN).