Microsoft Clarity

Web Source code Package

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.

Where this fits

Clarity is a web destination in the walkerOS flow:

Installation

npm install @walkeros/web-destination-clarity

Integrated
Bundled

import { startFlow } from '@walkeros/collector';
import { destinationClarity } from '@walkeros/web-destination-clarity';

await startFlow({
destinations: {
  clarity: {
    code: destinationClarity,
    config: {
      settings: {
        apiKey: '3t0wlogvdz',
        consent: {
          analytics: 'analytics_Storage',
          marketing: 'ad_Storage',
        },
      },
    },
  },
},
});

Add to your flow.json destinations:

"destinations": {
"clarity": {
  "package": "@walkeros/web-destination-clarity",
  "config": {
    "settings": {
      "apiKey": "3t0wlogvdz",
      "consent": {
        "analytics": "analytics_Storage",
        "marketing": "ad_Storage"
      }
    }
  }
}
}

See bundled mode setup | CLI reference

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
`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?.

* Required fields

Mapping

Per-event rules under config.mapping. For the standard rule fields (consent, condition, data, batch, name, policy) see mapping.

Property	Type	Description
`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.

Event

{
  "name": "product view",
  "data": {
    "id": "ers",
    "name": "Everyday Ruck Snack",
    "color": "black",
    "size": "l",
    "price": 420,
    "tags": [
      "sale",
      "featured"
    ]
  },
  "context": {
    "shopping": [
      "detail",
      0
    ]
  },
  "globals": {
    "pagegroup": "shop"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [],
  "consent": {
    "functional": true
  },
  "id": "9fce644f62659d89",
  "trigger": "load",
  "entity": "product",
  "action": "view",
  "timestamp": 1700000105,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}

Mapping

{
  "settings": {
    "set": {
      "map": {
        "product_tags": "data.tags"
      }
    }
  }
}

Out

clarity.setTag("product_tags", [
  "sale",
  "featured"
]);

clarity.event("product view")

Combined features

A purchase identifies the user, sets an order tag, upgrades the session, and fires the Clarity event in order.

Event

{
  "name": "order complete",
  "data": {
    "id": "0rd3r1d",
    "currency": "EUR",
    "shipping": 5.22,
    "taxes": 73.76,
    "total": 555
  },
  "context": {
    "shopping": [
      "complete",
      0
    ]
  },
  "globals": {
    "pagegroup": "shop"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [
    {
      "entity": "product",
      "data": {
        "id": "ers",
        "name": "Everyday Ruck Snack",
        "color": "black",
        "size": "l",
        "price": 420
      },
      "context": {
        "shopping": [
          "complete",
          0
        ]
      },
      "nested": []
    },
    {
      "entity": "product",
      "data": {
        "id": "cc",
        "name": "Cool Cap",
        "size": "one size",
        "price": 42
      },
      "context": {
        "shopping": [
          "complete",
          0
        ]
      },
      "nested": []
    },
    {
      "entity": "gift",
      "data": {
        "name": "Surprise"
      },
      "context": {
        "shopping": [
          "complete",
          0
        ]
      },
      "nested": []
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "662a6c3414b104d0",
  "trigger": "load",
  "entity": "order",
  "action": "complete",
  "timestamp": 1700000108,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}

Mapping

{
  "name": "Purchase",
  "settings": {
    "identify": {
      "map": {
        "customId": "user.id"
      }
    },
    "set": {
      "map": {
        "order_id": "data.id"
      }
    },
    "upgrade": {
      "value": "purchase"
    }
  }
}

Out

clarity.identify("us3r");

clarity.setTag("order_id", "0rd3r1d");

clarity.upgrade("purchase");

clarity.event("Purchase")

Consent granted

A walker consent command translates analytics and marketing grants into a Clarity.consentV2 call.

Event

{
  "analytics": true,
  "marketing": true
}

Out

clarity.consentV2({
  "analytics_Storage": "granted",
  "ad_Storage": "granted"
})

Consent revoked

A walker consent command with analytics and marketing denied calls Clarity.consentV2 with denied flags.

Event

{
  "analytics": false,
  "marketing": false
}

Out

clarity.consentV2({
  "analytics_Storage": "granted",
  "ad_Storage": "granted"
});

clarity.consentV2({
  "analytics_Storage": "denied",
  "ad_Storage": "denied"
})

Default event

A walker event becomes a Clarity.event call with the event name as the Clarity custom event.

Event

{
  "name": "product view",
  "data": {
    "id": "ers",
    "name": "Everyday Ruck Snack",
    "color": "black",
    "size": "l",
    "price": 420
  },
  "context": {
    "shopping": [
      "detail",
      0
    ]
  },
  "globals": {
    "pagegroup": "shop"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [],
  "consent": {
    "functional": true
  },
  "id": "b6c5ad59ae0993fc",
  "trigger": "load",
  "entity": "product",
  "action": "view",
  "timestamp": 1700000100,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}

Out

clarity.event("product view")

Destination identify

Destination-level identify calls Clarity.identify with the user id on every push as Clarity recommends.

Event

{
  "name": "page view",
  "data": {
    "domain": "www.example.com",
    "title": "walkerOS documentation",
    "referrer": "https://www.walkeros.io/",
    "search": "?foo=bar",
    "hash": "#hash",
    "id": "/docs/"
  },
  "context": {
    "dev": [
      "test",
      1
    ]
  },
  "globals": {
    "pagegroup": "docs"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [
    {
      "entity": "child",
      "data": {
        "is": "subordinated"
      }
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "c196e29b94c5999e",
  "trigger": "load",
  "entity": "page",
  "action": "view",
  "timestamp": 1700000103,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}

Out

clarity.identify("us3r");

clarity.event("page view")

Include data as tags

A mapping include flattens the event data section into Clarity.setTag calls before the event fires.

Event

{
  "name": "order complete",
  "data": {
    "id": "0rd3r1d",
    "currency": "EUR",
    "shipping": 5.22,
    "taxes": 73.76,
    "total": 555
  },
  "context": {
    "shopping": [
      "complete",
      0
    ]
  },
  "globals": {
    "pagegroup": "shop"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [
    {
      "entity": "product",
      "data": {
        "id": "ers",
        "name": "Everyday Ruck Snack",
        "color": "black",
        "size": "l",
        "price": 420
      },
      "context": {
        "shopping": [
          "complete",
          0
        ]
      },
      "nested": []
    },
    {
      "entity": "product",
      "data": {
        "id": "cc",
        "name": "Cool Cap",
        "size": "one size",
        "price": 42
      },
      "context": {
        "shopping": [
          "complete",
          0
        ]
      },
      "nested": []
    },
    {
      "entity": "gift",
      "data": {
        "name": "Surprise"
      },
      "context": {
        "shopping": [
          "complete",
          0
        ]
      },
      "nested": []
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "7305feb76e874113",
  "trigger": "load",
  "entity": "order",
  "action": "complete",
  "timestamp": 1700000107,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}

Mapping

{
  "include": [
    "data"
  ]
}

Out

clarity.setTag("data_id", "0rd3r1d");

clarity.setTag("data_currency", "EUR");

clarity.setTag("data_shipping", "5.22");

clarity.setTag("data_taxes", "73.76");

clarity.setTag("data_total", "555");

clarity.event("order complete")

Upgrade session

A completed order upgrades the Clarity session priority so it is retained beyond the sampling cap.

Event

{
  "name": "order complete",
  "data": {
    "id": "0rd3r1d",
    "currency": "EUR",
    "shipping": 5.22,
    "taxes": 73.76,
    "total": 555
  },
  "context": {
    "shopping": [
      "complete",
      0
    ]
  },
  "globals": {
    "pagegroup": "shop"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [
    {
      "entity": "product",
      "data": {
        "id": "ers",
        "name": "Everyday Ruck Snack",
        "color": "black",
        "size": "l",
        "price": 420
      },
      "context": {
        "shopping": [
          "complete",
          0
        ]
      },
      "nested": []
    },
    {
      "entity": "product",
      "data": {
        "id": "cc",
        "name": "Cool Cap",
        "size": "one size",
        "price": 42
      },
      "context": {
        "shopping": [
          "complete",
          0
        ]
      },
      "nested": []
    },
    {
      "entity": "gift",
      "data": {
        "name": "Surprise"
      },
      "context": {
        "shopping": [
          "complete",
          0
        ]
      },
      "nested": []
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "c56f49223b43a49a",
  "trigger": "load",
  "entity": "order",
  "action": "complete",
  "timestamp": 1700000106,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}

Mapping

{
  "name": "Purchase",
  "settings": {
    "upgrade": {
      "value": "purchase"
    }
  }
}

Out

clarity.upgrade("purchase");

clarity.event("Purchase")

Tags without event

A page view sets Clarity tags while silent suppresses the event, letting Clarity handle page tracking itself.

Event

{
  "name": "page view",
  "data": {
    "domain": "www.example.com",
    "title": "walkerOS documentation",
    "referrer": "https://www.walkeros.io/",
    "search": "?foo=bar",
    "hash": "#hash",
    "id": "/docs/"
  },
  "context": {
    "dev": [
      "test",
      1
    ]
  },
  "globals": {
    "pagegroup": "docs"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [
    {
      "entity": "child",
      "data": {
        "is": "subordinated"
      }
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "cc32ef88842c7cf8",
  "trigger": "load",
  "entity": "page",
  "action": "view",
  "timestamp": 1700000109,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}

Mapping

{
  "silent": true,
  "settings": {
    "set": {
      "map": {
        "page_id": "data.id"
      }
    }
  }
}

Out

clarity.setTag("page_id", "/docs/")

Custom tags

A product view sets Clarity session tags such as product color and id before firing the event.

Event

{
  "name": "product view",
  "data": {
    "id": "ers",
    "name": "Everyday Ruck Snack",
    "color": "black",
    "size": "l",
    "price": 420
  },
  "context": {
    "shopping": [
      "detail",
      0
    ]
  },
  "globals": {
    "pagegroup": "shop"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [],
  "consent": {
    "functional": true
  },
  "id": "ae3ef12c0d882b6e",
  "trigger": "load",
  "entity": "product",
  "action": "view",
  "timestamp": 1700000104,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}

Mapping

{
  "settings": {
    "set": {
      "map": {
        "product_color": "data.color",
        "product_id": "data.id"
      }
    }
  }
}

Out

clarity.setTag("product_color", "black");

clarity.setTag("product_id", "ers");

clarity.event("product view")

User login identify

A user login fires Clarity.identify with custom id, session id, page id, and friendly name then tracks the event.

Event

{
  "name": "user login",
  "data": {
    "id": "u-123",
    "name": "Jane Doe"
  },
  "context": {
    "dev": [
      "test",
      1
    ]
  },
  "globals": {
    "pagegroup": "shop",
    "pagetype": "home"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [
    {
      "entity": "child",
      "data": {
        "is": "subordinated"
      }
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "6ced3bde2abce9bf",
  "trigger": "test",
  "entity": "user",
  "action": "login",
  "timestamp": 1700000102,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}

Mapping

{
  "settings": {
    "identify": {
      "map": {
        "customId": "data.id",
        "customSessionId": "user.session",
        "customPageId": "globals.pagetype",
        "friendlyName": "data.name"
      }
    }
  }
}

Out

clarity.identify("u-123", "s3ss10n", "home", "Jane Doe");

clarity.event("user login")

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).

💡 Need implementation support?

elbwalker offers hands-on support: setup review, measurement planning, destination mapping, and live troubleshooting. Book a 2-hour session (€399)

Installation​

Configuration​

Settings​

Mapping​

Examples

Array tag values

Combined features

Consent granted

Consent revoked

Default event

Destination identify

Include data as tags

Upgrade session

Tags without event

Custom tags

User login identify

Consent translation​

Installation

Configuration

Settings

Mapping

Consent translation