Build a custom dashboard

Every project starts from the Product Health template — 23 components tuned to how SaaS accounts typically churn. It's a strong default, but no two products measure retention exactly the same way. A usage-based API tool, a seat-based collaboration app, and a consumer subscription each have their own tell-tale signals, and the template can't know yours out of the box.

This guide shows how to make the dashboard your own: adding components (the signals that drive the health score) and widgets (the charts that visualize them), built from the events you already send. No code — everything here happens in Settings.

Why customize

• Model a signal unique to your product. "Projects created," "API calls," "docs published" — whatever your version of getting value looks like.
• Match the weights to your business. If renewals in your world hinge on seat growth, weight expansion heavily; if they hinge on daily habit, weight frequency.
• Stop scoring what you don't collect. Disable a default signal you have no data for so it can't drag scores around for the wrong reason.
• Visualize a metric for the team. Put the number that matters in a QBR or a standup as a trend or a big-number tile.

The three layers

Customizing means working with three connected layers. The dashboard overview covers them in depth; in short:

The key distinction: a component decides what a signal means and how heavily it counts; a widget decides how a signal is drawn. You'll usually build a component when you want to influence the health score, and a widget when you just want to see a number.

Step 1 — Map your events (if needed)

Components read metrics, not raw event names. Before you build a component on a new signal, open Settings → Event map and confirm your raw event (e.g. project.created) maps to a metric (e.g. project_created). One raw type can fan out to several metrics, and the default mappings already cover the common billing, support, and survey events.

Step 2 — Build a scoring component

Open Settings → Components → New component. The guided builder walks you through it:

1. Pick a measure — how the signal is computed:

   Measure	What it does	Needs
   Count of events	How many times it happens in the window.	—
   Average of a field	Averages a numeric payload field (e.g. session minutes).	a field name
   Distinct count	Unique values — e.g. distinct active users.	a distinct field
   Days since last seen	Recency — days since it last happened (lower is healthier).	— (no window)

2. Choose the signal from the metric source picker — the metrics available from your event map.

3. Set the time window — 7, 14, 30, 90, or 180 days. (Days-since-last-seen has no window; it always measures recency to now.)

4. Direction & thresholds — choose Higher is healthier or Lower is healthier, then set good and warn. A signal scores 100 at good (or better) and 30 at warn (or worse), sliding linearly in between.

5. Weight — how heavily this signal counts in the weighted-average score.

A live summary sentence and a live preview update as you go, so you can see exactly what the component will measure before saving.

Preview before you commit

The preview runs the metric as a bounded dry run against your real accounts, so you see plausible numbers, not a guess. Each measure carries a cost badge — Cheap, Time-based, or Heavier — hinting how much work it is to compute across all accounts, so you can prefer a lighter equivalent when one exists.

Promote: the band-impact gate

When you're happy with it, Promote the component. Promotion is a two-step, reversible gate:

1. Dry run — ChurnWarn computes the band-impact diff: the distribution of accounts across Healthy / Watch / Risky / Cold / No-data before vs. after, and exactly how many accounts would move bands.
2. Confirm — only then does the component start counting toward the score.

This matters because a new weighted signal can shift many accounts at once. The diff shows the blast radius before you commit, so an aggressive threshold doesn't silently turn half your book "Cold" overnight.

Step 3 — Build a widget

Open Settings → Widgets → New widget. Widgets are pure visualization — they never affect the score:

1. Title the widget.

2. Aggregate — what the chart computes:

   Aggregate	What it does
   Count of events	How many events occurred.
   Sum of a field	Adds up a numeric payload field.
   Average of a field	Averages a numeric payload field.
   Distinct count	Unique values (e.g. active users).

3. Visualization — how it's drawn:

   Kind	Looks like
   Big number	A single total over the range, with a sparkline.
   Trend (area)	How the value moves over time.
   Bars	One bar per day or week.

4. Scope — All accounts (one chart across your whole book) or Per account (the same chart computed for an individual account).

5. Bucket — Daily or Weekly points.

The widget grid has a range toggle (7 / 30 / 90 days) so you can zoom the whole dashboard in or out. A widget can read a component you built or carry its own inline metric, so you can chart something without first turning it into a scored signal.

Component or widget — which do I need?

• Want it to change the health score and the account's band? Build a component and promote it.
• Just want to watch a number or a trend? Build a widget.
• Want both — a signal that scores and shows on the board? Build the component, then add a widget that reads it. Change the component once and the score and every widget update together.

Good to know

• Weights are relative. The score is a weight-proportional average, so you can retune one component without renumbering the rest.
• Disable rather than delete. Turning a default off keeps its history and lets you switch it back on later.
• One source per signal. If a metric arrives from both a direct integration and Segment, you'll double-count — see integrations.
• Editing a default reopens it in the same builder, so the built-ins are a working example of every measure and threshold.

Next

• Study the default components — each one is a worked example of a real scoring signal, with thresholds and weights you can copy.
• Connect integrations to feed components signals from other systems — billing, support, and CRM events that happen outside your product, so the SDK's auto-capture never observes them on its own. You can always send any event yourself through the SDK or HTTP API; integrations just spare you from wiring up each external source by hand.