First DistroFirstDistro
Back to Documentation
guides

Understanding health scores

Learn how Customer Insights calculates health scores and what they mean.

Last Updated: November 19, 2025

Overview

Health scores are calculated automatically for each customer account based on their product usage patterns. Scores range from 0-100 and are updated hourly.

Health score components

Health scores are calculated from three components:

1. engagement score (0-100)

Measures how actively customers are using your product.

Factors:

  • Recent event activity (last 7 days)
  • Event frequency and consistency
  • Feature adoption patterns
  • User activity levels

High engagement = Frequent, consistent product usage
Low engagement = Infrequent or declining usage

2. adoption score (0-100)

Measures how deeply customers are adopting your product.

Factors:

  • Number of features used
  • Feature diversity
  • Core feature usage
  • Advanced feature exploration

High adoption = Using many features, exploring advanced capabilities
Low adoption = Using only basic features, limited exploration

3. activity score (0-100)

Measures recent activity trends and momentum.

Factors:

  • Activity in last 24-48 hours
  • Activity trends (increasing/decreasing)
  • Milestone completion
  • User growth within account

High activity = Recent activity, positive trends
Low activity = Declining activity, no recent events

Overall health score

The overall health score is calculated as:

Health Score = (Engagement × 0.4) + (Adoption × 0.3) + (Activity × 0.3)

Weighting:

  • Engagement: 40% (most important)
  • Adoption: 30%
  • Activity: 30%

Health score ranges

Healthy (70-100)

  • Green indicator in dashboard
  • Customers are actively using your product
  • Low churn risk
  • Action: Continue monitoring, celebrate success

At-risk (40-69)

  • Yellow indicator in dashboard
  • Customers showing signs of disengagement
  • Moderate churn risk
  • Action: Proactive outreach recommended

Critical (0-39)

  • Red indicator in dashboard
  • Customers with very low engagement
  • High churn risk
  • Action: Immediate intervention needed

Health score trends

Health scores include trend indicators:

  • ↑ Improving - Score increased since last calculation
  • → Stable - Score remained similar
  • ↓ Declining - Score decreased since last calculation

Trends help identify:

  • Customers recovering from low engagement
  • Customers gradually disengaging
  • Customers maintaining healthy usage

Component trends

Each component (Engagement, Adoption, Activity) also has its own trend:

  • See which components are improving or declining
  • Identify specific areas needing attention
  • Focus outreach on specific improvement areas

How scores are updated

  1. Event collection - SDK tracks product usage events
  2. Hourly calculation - Cron job runs every hour
  3. Score computation - Health scoring algorithm processes events
  4. Dashboard update - Scores appear in Customer Insights dashboard

Factors affecting health scores

Positive factors

  • ✅ Frequent product usage
  • ✅ Using multiple features
  • ✅ Recent activity (last 24-48 hours)
  • ✅ Completing onboarding milestones
  • ✅ Adding new users to account
  • ✅ Exploring advanced features

Negative factors

  • ❌ Declining event frequency
  • ❌ No activity in last 7+ days
  • ❌ Using only basic features
  • ❌ No recent events
  • ❌ Account inactivity

Best practices

Track the right events

Focus on events that indicate product value:

  • Feature usage (not just page views)
  • Milestone completions
  • User actions (not just passive views)
  • Account-level events

Group by account

Always call FirstDistro.group() to associate events with accounts:

FirstDistro.group('acct_123', { name: 'Acme Corp' });

See the Getting Started guide for account grouping setup.

Track consistently

  • Track events for all key product actions
  • Ensure events include account context
  • Maintain consistent event naming

Interpreting health scores

High score (80-100)

  • Customer is highly engaged
  • Low churn risk
  • Likely to expand or renew
  • Action: Upsell opportunities, feature requests

Medium score (50-79)

  • Customer is moderately engaged
  • Some churn risk
  • May need re-engagement
  • Action: Check-in emails, feature education

Low score (0-49)

  • Customer is disengaged
  • High churn risk
  • Needs immediate attention
  • Action: Proactive outreach, win-back campaigns

Related documentation

All Documentation