Інтеграція 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'
Відповідь містить агреговані дані: мертві клікни, клікни гніву, швидкі повернення, глибину прокрутки для кожної сторінки.
Перевірка встановлення
// У консолі браузера
window.clarity // повинна бути функція, не undefined
// Перевірити, що скрипт завантажений
document.querySelector('script[src*="clarity.ms"]') // не null
// Примусово перевірити стан
window.clarity('upgrade', 'test_check');
У інтерфейсі Clarity → «Setup» показує статус «Recording» з кількістю сесій за останні 24 години. Перші записи з'являються впродовж кількох хвилин після початку трафіку.
Строки
Встановлення та верифікація — 30 хвилин. Налаштування користувацьких тегів та ідентифікації — 2 години. Інтеграція з GA4 та налаштування маскування — ще 1 година.