> Part of the walkerOS documentation. Project overview and full index: <https://www.walkeros.io/llms.txt>

# Microsoft Clarity

<!-- -->

[Web](#)[ ](https://github.com/elbwalker/walkerOS/tree/main/packages/web/destinations/clarity)

<!-- -->

[Source code](https://github.com/elbwalker/walkerOS/tree/main/packages/web/destinations/clarity)[ ](https://www.npmjs.com/package/@walkeros/web-destination-clarity)

<!-- -->

[Package](https://www.npmjs.com/package/@walkeros/web-destination-clarity)

[Microsoft Clarity](https://clarity.microsoft.com/) 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`](https://www.npmjs.com/package/@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[​](#installation "Direct link to 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](https://www.walkeros.io/docs/getting-started/modes/bundled.md) | [CLI reference](https://www.walkeros.io/docs/apps/cli.md)

## Configuration[​](#configuration "Direct link to Configuration")

This <!-- -->destination<!-- --> uses the standard <!-- -->destination<!-- --> config wrapper (consent, data, env, id, ...). For the shared fields see [destination<!-- --> configuration](https://www.walkeros.io/docs/destinations.md#configuration). Package-specific fields live under `config.settings` and are listed below.

## Settings[​](#settings "Direct link to 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?.                                                                                     |      |

\* Required fields

## Mapping[​](#mapping "Direct link to Mapping")

Per-event rules under `config.mapping`. For the standard rule fields (consent, condition, data, batch, name, policy) see [mapping](https://www.walkeros.io/docs/mapping.md).

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

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": "98df0f787946c90e",
  "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": "f920bde930158ca2",
  "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": "e05dfa76833663b4",
  "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": "1ee1c36a9eb52c96",
  "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": "0fce909307575dad",
  "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": "cd63c20510076808",
  "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": "69411a2d0304a691",
  "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": "c74cf962ef70807e",
  "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": "0b55f2e5f7dd625f",
  "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")
```

## Consent translation[​](#consent-translation "Direct link to 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).