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:

• Self-hosted — no managed analytics. The underlying data is in your database; you build whatever reporting you want on top.
• 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	Self-hosted	Solo	Team	Studio
Per-release view counts	build your own
Subscriber growth over time	build your own	—
Per-release read rate (reads / impressions)	build your own	—
Per-user read state (read/unread per release)	build your own	—
Per-group breakdowns	build your own	—
Email open rates (per send)	depends on SMTP
Email click rates (per send)	depends on SMTP
Widget open events	build your own

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

The dashboard lives at Settings → Analytics in your Herald project. It's the same data we expose programmatically (see Exporting below), rendered as charts and tables.

Top-line views:

• Subscriber growth — line chart of total email subscribers over time, with overlay points for each release publication so you can see whether announcements drive sign-ups
• Release performance — table of recent releases with view count, read rate, and click-through (when applicable). Sortable by any column.
• Top releases — most-viewed and most-read releases over a chosen time window

Date range: defaults to last 30 days; you can switch to 7-day, 90-day, or all-time. Time-series charts are bucketed daily for ranges <90 days and weekly above that.

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

Self-hosted installs have direct database access; the same metrics live in tables you can query directly. The API is a convenience for cloud customers and for self-hosted customers who'd rather not write SQL.