Microsoft Clarity
Microsoft Clarity provides session replays,
heatmaps and behavioural insights for web products, free and without sampling
caps. This destination forwards walkerOS events to Clarity via the official
@microsoft/clarity SDK,
translating events into Clarity.event(...) calls, resolving custom tags,
identities, session priority, and consent state.
Clarity is a web destination in the walkerOS flow:
Installation
- Integrated
- Bundled
Configuration
This destination uses the standard destination config wrapper (consent, data, env, id, ...). For the shared fields see destination configuration. Package-specific fields live under config.settings and are listed below.
Settings
| Property | Type | Description | More |
|---|---|---|---|
apiKey | string | Your Microsoft Clarity project ID (e.g. "3t0wlogvdz"). Find it in your Clarity dashboard under Settings → Setup. | |
consent | Record<string, string> | Translation table from walkerOS consent keys to Clarity ConsentV2 categories. Example: { "analytics": "analytics_Storage", "marketing": "ad_Storage" }. Required to get meaningful consent behavior — Clarity expects its own category names. | |
identify | any | walkerOS mapping value resolving to positional arguments for Clarity.identify(). Keys: customId (required), customSessionId?, customPageId?, friendlyName?. |
Mapping
Per-event rules under config.mapping. For the standard rule fields (consent, condition, data, batch, name, policy) see mapping.
| Property | Type | Description | More |
|---|---|---|---|
identify | any | Per-event identity mapping. Resolves to { customId, customSessionId?, customPageId?, friendlyName? } → Clarity.identify(...). | |
set | any | Explicit custom tag mapping. Resolved object keys become Clarity.setTag(key, value) calls. Array values pass through as string[] unchanged. | |
upgrade | any | Session priority reason. Resolves to a string → Clarity.upgrade(reason). Used to flag important sessions for retention beyond sampling. |
Examples
Array tag values
Array values such as product tags are passed through to Clarity.setTag preserving the array shape.
Combined features
A purchase identifies the user, sets an order tag, upgrades the session, and fires the Clarity event in order.
Consent granted
A walker consent command translates analytics and marketing grants into a Clarity.consentV2 call.
Consent revoked
A walker consent command with analytics and marketing denied calls Clarity.consentV2 with denied flags.
Default event
A walker event becomes a Clarity.event call with the event name as the Clarity custom event.
Destination identify
Destination-level identify calls Clarity.identify with the user id on every push as Clarity recommends.
Include data as tags
A mapping include flattens the event data section into Clarity.setTag calls before the event fires.
Upgrade session
A completed order upgrades the Clarity session priority so it is retained beyond the sampling cap.
Tags without event
A page view sets Clarity tags while skip suppresses the event, letting Clarity handle page tracking itself.
Custom tags
A product view sets Clarity session tags such as product color and id before firing the event.
User login identify
A user login fires Clarity.identify with custom id, session id, page id, and friendly name then tracks the event.
Consent translation
Clarity expects its own category names (analytics_Storage, ad_Storage).
walkerOS uses arbitrary consent keys, so translation is explicit: configure
settings.consent once and the destination maps every walker consent event
into Clarity.consentV2({ ... }). When all mapped keys are revoked, the
destination additionally calls Clarity.consent(false) (the legacy v1 API
that erases cookies and ends the session).