Microsoft Clarity Integration Pro - Heatmaps, Recordings & Consent

Installation instructions, documentation and FAQs for the Shopware plugin

Microsoft Clarity provides heatmaps, session recordings and insights for your shop - free of charge, without a session limit and without sampling. Microsoft Clarity Integration Pro integrates the service cleanly into Shopware 6 and takes care of cookie consent, custom tags and the protection of sensitive checkout data. All settings are made via the plugin configuration in the Shopware administration - code adjustments are not necessary.

  1. Integration of Microsoft Clarity (tracking code, loaded asynchronously)
  2. Integration into the Shopware Cookie Manager (Statistics, Marketing or Comfort groups can be selected)
  3. SHA256-hashed user identification for logged-in customers (no plain text PII to Microsoft)
  4. Custom tags for sales channel, language and customer group
  5. Automatic masking of all checkout entries (address, payment, e-mail)
  6. Purchase event on the finish page for conversion analyses

Prerequisites

  • Shopware 6.6 or 6.7
  • An active Microsoft Clarity project with a valid project ID (attachment free of charge at clarity.microsoft.com)
  • Active Shopware Cookie Manager - Clarity does not load without consent

Compatibility

  • Shopware 6.7 - fully tested, connection via the new CookieGroupCollectEvent-API
  • Shopware 6.6 - compatible via the classic CookieProviderInterface-API
  • Uses only the official Microsoft Clarity Client API (consent, set, identify, event, upgrade)
  • No third-party plug-ins required

Installation

  1. Purchase the plugin in the Shopware Store and install it in the shop.
  2. Under Extensions → My extensions activate.
  3. Clear cache and reload storefront with F5.
  4. Open the plugin configuration and enter the Microsoft Clarity project ID (see next section).

Furnishings

Create Microsoft Clarity project

  1. clarity.microsoft.com and log in (Microsoft, Google or Facebook account).
  2. Top left on My projects click.
  3. About New project fill out the form: Name (e.g. the shop name), website URL, appropriate category.
  4. Create project.

Copy out project ID

  1. After creating the new project, activate it via the project selection in the top right-hand corner.
  2. In the left menu click on Settings click.
  3. Right at the top is the Project ID (alphanumeric, e.g. abc1234xyz). Copy this ID.

Configure plugin

  1. In the Shopware administration Extensions → My extensions → Microsoft Clarity Integration Pro → Configuration open.
  2. Enter the project ID.
  3. If required, configure per sales channel if only certain channels are to be tracked.
  4. Save.

The project ID is validated when saving - only alphanumeric characters are accepted. Invalid entries are ignored and Clarity does not load.

1 - Basic configuration

The basic configuration switches Clarity on and determines how the cookie is categorised in the Cookie Manager.

FieldMeaning
Plugin activeSwitches the entire Clarity integration on or off.
Clarity Project-IDThe alphanumeric ID from the Clarity dashboard.
Cookie groupIn which Shopware cookie group the Clarity cookie is categorised: Statistics (default, GDPR recommendation), Marketing or Comfort.
Bypass cookie consentOnly for internal test shops: Clarity loads immediately without a cookie banner. Do not activate in production shops!

2 - Options

The options control additional Clarity features relating to customer recognition, conversion tracking and data protection in the checkout.

FieldMeaning
Activate user identificationCalls for logged-in customers clarity("identify", ) on. The customer ID is before hashed by SHA256 before sending - no plain text PII reaches Microsoft.
Purchase event on finish pageFires after completed order clarity("event", "purchase") on /checkout/finish.
Mask checkout fieldsWraps the entire checkout content in <div data-clarity-mask>. Clarity automatically hides all form entries (address, payment, e-mail) in session recordings and heatmaps.

3 - Custom tags

Custom tags are key-value pairs that are transferred to Clarity for each session (clarity("set", key, value)). They appear as filters in the Clarity dashboard, allowing heatmaps and recordings to be segmented by language, sales channel or customer group.

FieldMeaning
Tag sales channelSends the name of the current sales channel as a tag salesChannel.
Tag languageSends the current locale code (e.g. en-EN, en-GB) as day language.
Tag customer groupSends the name of the customer group as a tag customerGroup (only if the customer is logged in).

4 - Cookie banner & consent

After installation, the cookie appears biloba-clarity-enabled automatically in the Shopware Cookie Manager, in the configured group (statistics, marketing or convenience).

  • If the customer agrees, the Clarity script is loaded asynchronously and starts tracking.
  • If the customer does not agree, Clarity does not load - no data is sent to Microsoft.
  • If the customer later revokes consent, Clarity will no longer be loaded the next time the page is accessed.

The plugin supports both Shopware cookie APIs: the classic CookieProviderInterface (before 6.7.3) and the new CookieGroupCollectEvent-based API (6.7.3+).

5 - Checkout masking

When Mask checkout fields is active, the entire checkout (/checkout/*) to make all input fields invisible for Clarity:

  • Address entries
  • Payment data
  • E-mail address
  • Invoice address

In Clarity recordings, these fields appear as grey rectangles; heatmaps only show the position of the fields, not the content. This is the Native Clarity function via the HTML attribute data-clarity-mask - no magic of its own, but Microsoft standard.

FAQs

No. Clarity is a free tool from Microsoft, with no session limit and no sampling. Only this plugin costs money - because we have built the clean Shopware integration.

Only if the customer agrees to the cookie. Even then No plain text customer data the shop: the user identification is SHA256-hashed, checkout fields are masked. Clarity receives anonymous transaction data and the custom tags configured in the plugin.

Check the project ID for typing errors (must be alphanumeric), check in the browser devtools whether the Clarity script with the ID biloba-clarity-script is loaded, agree to the cookie banner or activate the bypass mode for the test. Clarity typically takes 20-30 minutes for the first session to appear in the dashboard.

The cookie entry biloba-clarity-enabled is registered in the Cookie Manager regardless of the UI used. A third-party banner must set the same cookie name for the consent to be recognised correctly.

Sales channel, language and customer group are currently available in the UI. Custom tags via Twig extension are available via the official Clarity API (clarity("set", key, value)) is possible at any time - please contact our support team.

Only if the customer has previously agreed or the bypass mode is active. The purchase-The event is only fired if Clarity is already running - nothing is tracked afterwards.

Support

If you have any questions or problems, please do not hesitate to contact us: