Sync rage clicks, scroll depth, and engagement signals from Microsoft Clarity’s Data Export API and use them in automation rules.
Microsoft Clarity provides behavioural metrics — rage clicks, dead clicks, scroll depth, engagement time — for each landing page. This integration uses Clarity’s Data Export API (not the tracking script alone), so a per-business Clarity project ID and API token are required.Open it from a business’s Settings → Data Sources → Clarity.
This is a backend API integration, not a JavaScript snippet. Clarity must already be installed and collecting data on the client’s site before you connect it here.
The Clarity panel surfaces connection state and credentials:
Status badge — Connected when a token is stored and verified.
Description — Sync rage clicks, scroll depth, and other behavioral metrics from Microsoft Clarity. Generate a token at Clarity → Settings → Data Export → Generate new API token. The Clarity API allows 10 calls per project per day — the daily scheduler uses 4 of those.
Last synced — Timestamp of the most recent successful sync (for example, 31/05/2026, 05:00:46).
The Data Export API has hard limits the integration respects:
10 calls per project per UTC day.
1–3 days of data per request (numOfDays).
Up to 3 dimensions per call.
No pagination — up to ~1,000 rows per response.
The daily scheduler uses 4 of the 10 daily calls to cover the dimension combos described below. That leaves 6 calls for manual tests and the client portal’s connection test.
Each API call slices data by up to three of these dimensions:Browser, Device, Country/Region, OS, Source, Medium, Campaign, Channel, URLThe daily scheduler runs four default combos (one API call each):
Clarity returns groups including Traffic, ScrollDepth, EngagementTime, DeadClickCount, RageClickCount, ExcessiveScroll, QuickbackClick, ScriptErrorCount, ErrorClickCount, plus PopularPages, PageTitle, and ReferrerUrl.The sync normalises and stores these fields per dimension tuple:
Stored field
Source group (typical)
sessions
Traffic
bot_sessions
Traffic
distinct_users
Traffic
pages_per_session
Traffic
scroll_depth
ScrollDepth
engagement_time_ms
EngagementTime
dead_clicks
DeadClickCount
rage_clicks
RageClickCount
excessive_scroll
ExcessiveScroll
quick_backs
QuickbackClick
script_errors
ScriptErrorCount
error_clicks
ErrorClickCount
Dimension values land in columns like url, device, country, source, campaign, channel, browser, os, medium. URLs are normalised for consistent joins. Raw API rows are also kept in raw_payload for audit and debugging.Rows are stored in clarity_daily_metrics keyed by (business_id, date, dimension_hash) so different breakdowns don’t get summed together incorrectly.
Configuration — Saving credentials writes them to clarity_business_config. Test verifies the token (uses 1 daily call).
Scheduled sync — The daily clarityScheduler runs once per UTC day per enabled business, fetches 1 day of data, upserts into clarity_daily_metrics, and tracks each job in clarity_sync_jobs.
Failure handling — Bad auth disables the config automatically. Rate-limit errors leave it enabled so it retries the next UTC day.
Client portal — The same config and test endpoints are available under client-user routes for client-facing setup.
There is no Clarity metrics report screen in the frontend today — only this connection/settings panel. The data is consumed by the rules engine (below).
Synced data is rolled up business-wide over the rule’s date window via getBusinessBehavioralAggregates (using the Device,URL slice to avoid double-counting).Those aggregates feed the rule builder and are attached to every campaign / ad set / ad evaluation:
Metric
Description
clarity_sessions
Total sessions.
clarity_rage_clicks
Total rage clicks.
clarity_dead_clicks
Total dead clicks.
clarity_excessive_scroll
Total excessive-scroll events.
clarity_quick_backs
Total quick-back events.
clarity_rage_click_rate
Rage clicks ÷ sessions.
clarity_dead_click_rate
Dead clicks ÷ sessions.
clarity_quick_back_rate
Quick backs ÷ sessions.
clarity_scroll_depth
Average scroll depth.
clarity_engagement_time_ms
Average engagement time (ms).
If Clarity isn’t configured or has no data for the window, values are null and conditions that depend on them don’t trigger — rules still run for other metrics.Example rules:
Pause spend when clarity_rage_click_rate exceeds a threshold over the last 7 days.
Send an alert when clarity_dead_clicks spikes after a landing page change.
getUrlBehavioralAggregates (per landing URL) exists in the model but isn’t yet called elsewhere. Per-URL rules and optimiser logic are not active today — only business-wide aggregates are used.
