Analytics & Reporting

Overview

Herald tracks how your changelog actually performs — who's reading it, what entries land, how your subscriber list is growing. The depth of analytics depends on your tier:

• Solo — basic per-release view counts.
• Team and Studio — full analytics dashboard: subscriber growth, per-release view counts, per-release read rates, per-group breakdowns.

Analytics are first-party — Herald does not embed third-party trackers in your widget or hosted page. The data you see is what we measure server-side from page loads, widget opens, and email opens.

What gets tracked

Metric	Solo	Team	Studio
Per-release view counts
Subscriber growth over time	—
Per-release read rate (reads / impressions)	—
Per-user read state (read/unread per release)	—
Per-group breakdowns	—
Email open rates (per send)
Email click rates (per send)
Widget open events

What we deliberately don't track: individual visitor IPs, fingerprinting, third-party ad-network data. Per-user analytics only work when you've signed a JWT identity for the user (see Per-user read tracking below) — anonymous visitors are counted as anonymous traffic.

The analytics dashboard

Open your project and click Analytics in the project nav. Top-line views (last 30 days by default):

• Subscribers — total / confirmed / unconfirmed / unsubscribed counts
• Subscriber growth — chart of new subscribers over time
• Widget engagement — impressions, opens, open rate, release clicks, subscribe events
• Widget events over time — chart with peak day annotated
• Top releases by widget clicks
• Release views — all-time / last 30 days / unique readers
• Views over time
• Top releases by views

Date range: last 30 days by default.

Per-user read tracking

The widget tracks which releases each visitor has seen, so the unread badge is meaningful. 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 makes the analytics dashboard's "read rate" meaningful — without per-user identity, we can't distinguish "100 unique users read this once" from "1 user read this 100 times." See the Widget docs for how to wire JWT identity into the widget init.

Analytics by group (Team+)

If you've defined audience groups in Herald (Settings → Audiences), the analytics dashboard surfaces per-group breakdowns automatically. For each release, you can see:

• How many users in each targeted group saw the release
• How many in each group marked it read
• How long it took (median) for users in each group to read after publication

This is the metric that tells you whether your beta-feature announcement actually reached your beta cohort, or whether your enterprise-tier customers are catching the security updates you targeted at them. Without group analytics, segmentation is "we sent it" — with group analytics, it's "we sent it and we know who looked."

Group analytics depend on per-user identity (JWT) being passed in the widget init. Anonymous visitors don't appear in group breakdowns because there's no group membership signal for them.

Exporting data

All dashboard metrics are also available via Herald's JSON API at /api/v1/analytics. Endpoints expose the same per-release, per-subscriber, and per-group views the dashboard uses, scoped by your project API key.

Common patterns:

• Mirror to your own warehouse — schedule a daily fetch from /api/v1/analytics/releases?since=YYYY-MM-DD into your data store of choice
• Wire to Slack or Discord — combine with the publish webhook (Team+) to post both publish events and aggregated read stats once a week
• Embed in your own admin tool — pull the same data into your internal dashboards, no need to send teammates to the Herald UI

The API is available on cloud plans, so you can pull the same metrics into your own tools without writing SQL.