Engagement Scoring

Calculates a 0-100 engagement score for each session based on behavioral signals. Implemented in scoringService.ts. Optimized for real estate websites where most traffic lands on single-page project pages.

Scoring Formula (Real Estate Optimized)

Factor	Points	Calculation
Duration	0-35	1 point per 10 seconds, caps at ~6 minutes (350s)
Scroll Depth	0-30	1 point per 3.33% scroll depth, full scroll = 30
Click Count	0-20	1 point per click, caps at 20
Return Visits	0-15	5 points per return session, caps at 3 returns

Total: max 100 points

Why These Factors for Real Estate

• Duration — A buyer spending 5-10 min reading floor plans and amenities shows strong intent
• Scroll Depth — Reaching the pricing/contact section at the bottom = high intent
• Clicks — Gallery photos, floor plan tabs, brochure downloads = active interest
• Return Visits — Coming back to the same property page = serious buyer
• No page count — Real estate sites often have a single page per project, making page views meaningless

Engagement Labels

Score	Label	Recommended Action
0-20	Cold	Bounced or bot — low priority
21-45	Warm	Browsed briefly — follow up within 24h
46-70	Hot	Read the page, looked at details — call within 2h
71-100	Very Hot	Deep engagement + return visits — call immediately

Examples

Scenario	Duration	Scroll	Clicks	Returns	Score	Label
Bounce (5s, no interaction)	0	0	0	0	0	Cold
Light browse (60s, 50% scroll, 3 clicks)	6	15	3	0	24	Warm
Engaged visitor (3min, 80% scroll, 10 clicks)	18	24	10	0	52	Hot
Returning buyer (5min, 100% scroll, 15 clicks, 2 returns)	30	30	15	10	85	Very Hot

When Scoring Happens

The engagement score is calculated at session end (/track/session/end) and stored in sessions.engagement_score. When a lead is submitted, the score is recalculated from the active session and stored on the lead record.

Data Sources

1. Session record — started_at / ended_at timestamps for duration
2. Events aggregate — getEventCountsBySession() returns click count and max scroll depth
3. Fingerprint record — total_sessions for return visit count