Installing the Herald Widget

A small JS-powered popup that shows your changelog entries inside your product. Users open it from a trigger button. Unseen releases show a badge/dot.

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 or near the user menu.

<script
  src="https://widget.herald.app/v1/widget.js"
  data-project-id="YOUR_PROJECT_ID"
  defer></script>

Get your YOUR_PROJECT_ID from Settings → Widget in your Herald project. The script is async and lazy-loaded — initial paint is under 50ms and it doesn't block your app's load.

That's the whole install. The widget renders a small trigger button in the position you've configured (default: bottom-right) and shows your latest changelog entries when clicked. Unread releases display a badge automatically.

Configuration options

Position: bottom-right, bottom-left, top-right, top-left
Trigger button selector: attach to existing button or use default
CORS domains: lock to specific origins

The unread badge

The widget tracks which releases a visitor has seen. Unseen releases show a dot on the trigger. Works anonymously (localStorage) or per-user with JWT auth.

CORS origin control

In Settings → Widget, add your product domain. The script loads only on approved domains — important for production security.

JWT authentication (Team+)

On Team+ plans, you can sign a JWT containing the user ID from your backend and pass it to the widget. This unlocks user-specific private views, per-user analytics, and group-based targeting. See JWT auth article.