Интеграция Clarity (Microsoft) на сайт

Интеграция Clarity (Microsoft) на сайт

Microsoft Clarity — бесплатный инструмент для записи сессий и построения тепловых карт. Нет ограничений по объёму трафика, хранит записи 90 дней, интегрируется с Google Analytics 4. Подходит как замена или дополнение к Hotjar на высоконагруженных сайтах.

Установка

Прямая вставка:

<!-- Перед </head> -->
<script type="text/javascript">
(function(c,l,a,r,i,t,y){
    c[a]=c[a]||function(){(c[a].q=c[a].q||[]).push(arguments)};
    t=l.createElement(r);t.async=1;t.src="https://www.clarity.ms/tag/"+i;
    y=l.getElementsByTagName(r)[0];y.parentNode.insertBefore(t,y);
})(window, document, "clarity", "script", "YOUR_PROJECT_ID");
</script>

Через GTM: Clarity есть в галерее GTM как готовый тип тега — достаточно ввести Project ID.

NPM:

npm install clarity-js

import { clarity } from 'clarity-js';
clarity.start({
  projectId: import.meta.env.VITE_CLARITY_PROJECT_ID,
  upload: 'https://m.clarity.ms/collect',
  expire: 365,
  lean: false,
  track: true,
  content: true,
});

Кастомные теги

Clarity позволяет прикреплять произвольные метаданные к сессиям — аналог identify в других системах:

// Установка тегов — вызывается в любой момент
window.clarity('set', 'user_id', 'usr_12345');
window.clarity('set', 'plan', 'enterprise');
window.clarity('set', 'page_type', 'product_detail');
window.clarity('set', 'ab_variant', 'B');

// Множественные значения для одного ключа
window.clarity('set', 'tag', 'vip');
window.clarity('set', 'tag', 'returning');

Теги доступны в фильтрах при просмотре записей: «покажи сессии, где plan = enterprise и page_type = checkout».

Идентификация пользователей

// Привязать сессию к пользователю
window.clarity('identify', 'unique_user_id', 'session_custom_id', 'page_custom_id', 'friendly_name');

// Пример для залогиненного пользователя
window.clarity(
  'identify',
  user.id,                          // уникальный ID пользователя
  `session_${Date.now()}`,          // опциональный ID сессии
  window.location.pathname,          // опциональный ID страницы
  user.email                         // отображаемое имя в интерфейсе
);

Кастомные события

// Отправить событие с контекстом
window.clarity('event', 'checkout_started');
window.clarity('event', 'form_error', 'phone_field_invalid');
window.clarity('event', 'video_played', 'intro_video');

События отображаются в таймлайне записи — можно перейти к конкретному моменту, когда произошло событие.

Интеграция с GA4

В настройках Clarity: «Settings → Integrations → Google Analytics» — выбрать нужное свойство GA4. После активации:

• В GA4 появится кастомное измерение clarity_session_url с ссылкой на запись Clarity
• В Clarity можно фильтровать сессии по GA4-сегментам
• Clarity-данные видны в GA4 через BigQuery-экспорт

SPA и трекинг маршрутов

// React Router
import { useEffect } from 'react';
import { useLocation } from 'react-router-dom';

export function ClarityRouteTracker() {
  const location = useLocation();

  useEffect(() => {
    // Устанавливаем тег с текущим маршрутом
    window.clarity?.('set', 'page', location.pathname);
    // Уведомляем об изменении страницы
    window.clarity?.('event', 'page_change', location.pathname);
  }, [location.pathname]);

  return null;
}

Маскировка данных

Clarity маскирует поля с типом password автоматически. Для остальных — через атрибуты:

<!-- Полное скрытие элемента из записей -->
<div data-clarity-mask="True">
    <span>Паспорт: 4510 123456</span>
</div>

<!-- Разрешить показ (если родитель замаскирован) -->
<div data-clarity-mask="True">
    <p>Приватные данные</p>
    <button data-clarity-unmask="True">Публичная кнопка</button>
</div>

Через настройки проекта: «Settings → Masking» — можно задать «Strict» режим, который маскирует весь текст на сайте и размаскировать только нужные блоки через data-clarity-unmask.

Работа с API Clarity

Clarity предоставляет REST API для программного доступа к данным:

# Получить метрики за период
curl -X GET \
  'https://www.clarity.ms/api/v1/projects/YOUR_PROJECT_ID/metrics?startDate=2024-01-01&endDate=2024-01-31' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

Ответ содержит агрегированные данные: dead clicks, rage clicks, quick backs, scroll depth по каждой странице.

Проверка установки

// В консоли браузера
window.clarity  // должна быть функция, не undefined

// Проверить, что скрипт загружен
document.querySelector('script[src*="clarity.ms"]')  // не null

// Принудительно проверить состояние
window.clarity('upgrade', 'test_check');

В интерфейсе Clarity → «Setup» показывает статус «Recording» с числом сессий за последние 24 часа. Первые записи появляются через несколько минут после начала трафика.

Сроки

Установка и верификация — 30 минут. Настройка кастомных тегов и идентификации — 2 часа. Интеграция с GA4 и настройка маскировки — ещё 1 час.