Microsoft Clarity Tag Setup Guide

Microsoft Clarity is a free-to-use analytics product built to help website managers improve their website experiences by better understanding site visitor behavior.

Tag Tips

Use mapping to dynamically override the project ID value
For more information, see Bing: Microsoft Clarity is now Generally Available

Tag Configuration

Go to the tag marketplace to add a new tag. For more information about how to add a tag, see Manage tags.

When adding the tag, configure the following settings:

Project ID: The Clarity project ID. You can find your project ID from your Clarity project URL. For example, https://clarity.microsoft.com/projects/view/PROJECT_ID/.
Ad Storage Consent: Set the default consent for Ad Storage. Dynamically update this value by mapping the ad_storage parameter in the Data Mappings section.
Analytics Storage Consent: Set the default consent for Analytics Storage. Options are Not set, Granted, and Denied. When set to Not set, analytics storage follows the Ad Storage Consent setting. Dynamically update this value by mapping the analytics_storage parameter in the Data Mappings section.
Automatically read from Tealium Consent Cookie: If set to true, consent is set based on the Tealium consent manager.

This tag uses Clarity’s Consent API v2, which sends independent ad and analytics storage signals. Consent API v2 is enforced for EEA, UK, and Switzerland visitors.

There are two options to implement consent mode for this tag:

Use client-side consent management and automatically read the Tealium Consent cookie.
Add a JavaScript Code extension to map consent choices and category mappings from your consent management platform (CMP) to this tag.

As visitors make their consent choices, the tag will choose the appropriate approach for first and third-party cookies:

Granted: Both first-party and third-party cookies can be read and written.
Denied: First-party cookies are neither read nor written, and third-party cookies are read-only for fraud and spam purposes, not for advertising.

To implement consent mode for this tag using client-side consent management, set Automatically read from Tealium Consent Cookie to true in the tag configuration.

JavaScript Code extension

To map end-user consent choices to Microsoft consent mode settings, use the JavaScript Code extension. Configure the extension as follows:

Set Scope to After Load Rules (default)
Set Occurrence to Run Always
Enter the JavaScript code for your CMP. You can customize the following code template for your CMP by replacing CUSTOM_LOGIC with the logic for your vendor.

b.consent_decision = (tealiumConsentRegister && tealiumConsentRegister.currentDecision) || [];
b.microsoft_ad_storage_consent = CUSTOM_LOGIC ? 'granted' : 'denied';

For example, the following code is for OneTrust.

// After Load Rules - Run Always
b.consent_decision = (tealiumConsentRegister && tealiumConsentRegister.currentDecision) || [];
b.microsoft_ad_storage_consent = b.consent_decision.indexOf('C0004') !== -1  ? 'granted' : 'denied';

If you use these exact variable names, no additional mapping is required. The latest version of the tag uses these variables by default. Overwrite these variables by mapping the ad_storage parameter to attributes for your specific case.

Load Rules

Load the tag on all pages or set conditions for when your tag will load. For more information, see About load rules.

Data Mappings

Mapping is the process of sending data from a data layer variable to the corresponding destination variable of the vendor tag. For more information, see About data mappings.

The available categories are:

Standard

Variable	Description
`project_id`	The Clarity project ID. You can find your project ID from your Clarity project URL. For example, `https://clarity.microsoft.com/projects/view/PROJECT_ID/`.
`ad_storage`	Ad Storage Consent. Overrides the Ad Storage Consent configuration setting. Valid values: `granted` or `denied`.
`analytics_storage`	Analytics Storage Consent. Overrides the Analytics Storage Consent configuration setting. Valid values: `granted` or `denied`.

Events

To map events, refer to Create an Event Mapping

Event	Description
`enable_consent`	Enable consent
`disable_consent`	Disable consent

Custom event names configured in the Events tab are forwarded to Clarity as custom events. Use the custom_event_name destination in the Custom Events category for event-specific mapping.

Map to the Cookie Consent destination to control cookie consent based on a user’s consent state.

Variable	Description
`grant`	Grant cookie consent. Sends Consent API v2 signals with `granted` for both ad and analytics storage.
`revoke`	Revoke cookie consent. Erases Clarity cookies.

Identify

Map the following destinations to call the Clarity Identify API on each tag fire. The Identify API is called only when custom_user_id is mapped and non-empty.

Variable	Description
`custom_user_id`	Custom user identifier. Required to trigger the Identify API call.
`session_id`	Session identifier.
`page_id`	Page identifier.
`friendly_name`	Human-readable label for the session.

Custom Tags

Variable	Description
`tag.{key}`	Custom tag. Calls `clarity('set', key, value)` with the mapped value. Accepts a string or an array of strings. Replace `{key}` with the tag key name.

Custom Events

Variable	Description
`custom_event_name`	A custom event name forwarded to Clarity. Calls `clarity('event', name)`.

Upgrade

Variable	Description
`upgrade_reason`	Reason for upgrading the Clarity session recording quality. Calls `clarity('upgrade', reason)`. For more information, see Clarity API.