# Microsoft Clarity

[Microsoft Clarity](https://clarity.microsoft.com/) is a heatmap and session recording tool that helps you better understand how users are interacting with your website.

RudderStack supports Microsoft Clarity as a web device mode destination to which you can seamlessly send your event data.

## Connection compatibility

{{< destination-config >}}

## Setup

1. In your [RudderStack dashboard](https://app.rudderstack.com/), set up a source.
2. Go to the **Overview** tab of your source and select **Add Destination** > **Create new destination**.

{{< image src="images/event-stream-destinations/add-new-destination.webp" alt="Add new destination in RudderStack dashboard" >}}

3. Select **Microsoft Clarity** from the list of destinations. Then, click **Continue**.

## Connection settings

| Setting | Description |
| :-----| :-----| 
| Project ID | Enter your [Microsoft Clarity project ID](#faq). |
| Microsoft Clarity Cookie Consent | Turn on this toggle to allow RudderStack to call the Microsoft Clarity API to track the users using a cookie. <br /><br />{{< info >}}If the **Cookies** setting is enabled in the Clarity project settings, then you need not enable the **Microsoft Clarity Cookie Consent** dashboard setting. {{< /info >}} |
| Client-side Events Filtering | This setting lets you specify which events should be blocked or allowed to flow through to Microsoft Clarity. <br /><br />See [Client-side Events Filtering]({{< ref "sources/event-streams/sdks/event-filtering.md" >}}) for more information on this setting. |
| Use device mode to send events | This setting is toggled on by default as this is a [web device mode]({{< ref "destinations/rudderstack-connection-modes.md#device-mode" >}})-only destination |
| Consent management settings | Configure the consent management settings for the specified source by choosing the **Consent management provider** from the dropdown and entering the relevant consent category IDs. <br /><br />See [Consent Management in RudderStack]({{< ref "data-governance/consent-management/overview.md" >}}) for more information on this feature.

## Identify

You can use the [`identify`]({{< ref "event-spec/standard-events/identify.md" >}}) events to create a new user in Microsoft Clarity.

A sample `identify` call is shown below:

```javascript
rudderanalytics.identify("1hKOmRA4GRlm", {
  name: "Alex Keener",
  email: "alex@example.com"
});
```

By default, Clarity uses cookies to track your users and gather the session data. You can configure your Clarity project to require [cookie consent](https://learn.microsoft.com/en-us/clarity/cookie-consent), that is, Clarity **will not** place a cookie until a user provides consent.

{{< image src="images/event-stream-destinations/clarity-cookie-consent.webp" alt="Microsoft Clarity cookie consent enabled" >}}

In this case, to track the user sessions via the cookie, make sure to enable the [**Microsoft Clarity Cookie Consent** setting](#connection-settings) in the RudderStack dashboard. This setting indicates that RudderStack can call the Clarity API to track the users via a cookie once a user provides consent.

### Supported mappings

RudderStack maps the following `identify` attributes to the corresponding Microsoft Clarity properties:

| RudderStack property | Microsoft Clarity property | 
| :-----| :------| 
| `userId` <br/> <span style="color: #4D4DFF;font-size:12px;">Required</span> | `customuserid` |
| `context.sessionId` | `customsessionid` |
| `context.traits.customPageId` | `custompageid` |

## Track

You can use the [`track`]({{< ref "event-spec/standard-events/track.md" >}}) events to send custom events to Microsoft Clarity. RudderStack maps these events to Clarity's [custom events](https://learn.microsoft.com/en-us/clarity/setup-and-installation/clarity-api#add-custom-events) to help you track specific user actions on your website.

A sample `track` call is shown below:

```javascript
rudderanalytics.track("Product Added", {
  productId: "123",
  category: "Shoes"
});
```

RudderStack maps the `track` event to Microsoft Clarity's API by sending the event name to Clarity. The implementation uses the following mapping:

```javascript
window.clarity("event", "Product Added");
```

{{< warning >}}
Microsoft Clarity's custom events accept only the event name. Event properties are not supported and will be ignored.
{{< /warning >}}

### Automatic mappings

Microsoft Clarity automatically classifies your `track` events to the following [Smart Events](https://clarity.microsoft.com/blog/an-overview-of-smart-events/), based on your [pre-configured mappings specified in the Microsoft Clarity dashboard](https://learn.microsoft.com/en-us/clarity/setup-and-installation/smart-events):

- `Purchase`
- `Add to Cart`
- `Begin Checkout`
- `Contact Us`
- `Submit Form`
- `Request Quote`
- `Sign Up`
- `Login`
- `Download`

## FAQ 

#### Where can I find the Microsoft Clarity project ID?

To get your Microsoft Clarity project ID, follow these steps:

1. Log into your <a href="https://clarity.microsoft.com/projects">Microsoft Clarity dashboard</a>.
2. Select your Microsoft Clarity project and go to **Settings** > **Overview** to get your project ID:

{{< image src="images/event-stream-destinations/clarity-project-id.webp" alt="Microsoft Clarity project ID" >}}