Mapa de calor, gravação de sessão e sinais de frustração de graça. Veja como instalar pelo código, GTM ou NPM, enviar eventos, tratar consentimento e exportar dados pela API.
Índice do artigo
Para se aprofundar
Para se aprofundar, o time da Métricas Boss trata desse assunto em: Microsoft Copilot integrado ao Clarity.
- O que é o Microsoft Clarity?
- Como instalar o Clarity: 3 caminhos
- A API do Clarity: eventos, tags e identificação
- Consentimento de cookies: o ponto que ninguém configura
- Mascaramento de dados sensíveis
- Exportando dados com a Data Export API
- Clarity em aplicativos: os SDKs mobile
- Os erros que mais aparecem
- Perguntas frequentes sobre Microsoft Clarity
Existem duas formas de usar o Microsoft Clarity. A primeira: colar o script, assistir a meia dúzia de gravações e concluir que “o usuário não entende o site”. A segunda: instalar com consentimento, marcar os eventos que importam e segmentar as sessões pelo que realmente gera receita.
Este guia é a segunda forma.
O que é o Microsoft Clarity?
O Clarity é uma ferramenta de behavior analytics da Microsoft que mostra como as pessoas usam o site: gravações de sessão, mapas de calor, sinais de frustração (rage clicks, dead clicks) e um dashboard de comportamento. Cada conta aceita um número ilimitado de projetos, um para cada domínio ou site.
Em uma frase: o GA4 diz quantas pessoas abandonaram o checkout; o Clarity mostra por quê.
Ele não substitui a ferramenta de analytics. Complementa. O GA4 é o placar; o Clarity é a gravação do jogo.
Como instalar o Clarity: 3 caminhos
Crie a conta em clarity.microsoft.com e adicione um projeto com nome e URL do site. Cada projeto recebe um código de rastreamento próprio, e a configuração é feita na aba Settings.
1. Código manual no head. Em Settings > Setup, copie o código pela opção “Get tracking code” e cole na seção head do site. O mesmo script funciona em vários subdomínios. É o caminho mais simples, mas o menos governável.
2. Google Tag Manager (o caminho recomendado). Na galeria de modelos da comunidade do GTM, pesquise “Microsoft” e escolha o template oficial; depois informe o Project ID, que fica em Settings > Overview no Clarity. Com o GTM você controla o acionador, condiciona ao consentimento e versiona a mudança.
3. Pacote NPM. Para aplicações JavaScript modernas (React, Next, Vue), existe o pacote oficial @microsoft/clarity, que inicializa a ferramenta direto no código do projeto.
Há ainda integrações nativas com Google Analytics, Shopify, WordPress, Wix e Squarespace.
Como validar: publicado o código, o painel mostra dados em tempo real, com o número de usuários ativos. Se nada aparecer, compare o script instalado com o exibido em Setup > Installation methods > Install manually.
A API do Clarity: eventos, tags e identificação
É aqui que o Clarity deixa de ser “um monte de gravação” e vira ferramenta de análise. O Clarity ID funciona como chave da API, sem outra chave e sem custo de uso.
// Evento personalizado
window.clarity("event", "checkout_erro_frete");
// Tag customizada (chave e valor)
window.clarity("set", "tipo_cliente", "recorrente");
// Identificação do usuário
window.clarity("identify", "id-interno-123");
// Consentimento (ver próxima seção)
window.clarity("consentv2", { ad_Storage: "granted", analytics_Storage: "granted" });
Tags aceitam como valor uma string ou uma lista de strings. Na identificação, só o custom-id é obrigatório; sessão, página e nome amigável são opcionais. Eventos enviados pela API aparecem junto com os Smart Events nos filtros, no dashboard e nas gravações.
Boa prática: os eventos do Clarity devem espelhar os nomes dos eventos do GA4 e sair da mesma camada de dados. Um dicionário, duas ferramentas.
Consentimento de cookies: o ponto que ninguém configura
Por padrão o Clarity grava cookie first-party assim que carrega. Para respeitar o banner de cookies, desative em Settings > Setup a gravação de cookies por padrão e passe a decisão do usuário pela API.
O método recomendado é o consentv2, com dois sinais (ad_Storage e analytics_Storage), cada um granted ou denied. Com consentimento negado, o Clarity opera em modo limitado: gera um ID único por pageview e não persiste a sessão em cookies. Você perde a jornada entre páginas desse usuário, mas continua vendo a página isolada.
Desde 31 de outubro de 2025 o Clarity exige sinal de consentimento válido para visitas do Espaço Econômico Europeu, Reino Unido e Suíça. Para a LGPD, a decisão de como tratar o consentimento é do jurídico e do DPO; o papel da implementação é garantir que o sinal chegue certo.
Como testar: no console do navegador, a chamada clarity(‘metadata’, …) retorna o objeto consentStatus, que deve refletir a escolha feita no banner.
Mascaramento de dados sensíveis
Gravação de sessão sem mascaramento é vazamento de dado esperando para acontecer. O atributo HTML data-clarity-mask=”true” oculta um elemento e data-clarity-unmask=”true” revela. Aplique em campos de CPF, endereço, pagamento e áreas logadas.
Exportando dados com a Data Export API
Para levar métricas do Clarity para BigQuery, Looker Studio ou planilha, existe a Data Export API. O acesso usa token JWT gerado por um admin em Settings > Data Export > Generate new API token. Dois limites mudam o desenho da rotina: no máximo 10 requisições por projeto por dia, e resultados em UTC.
Tradução: é uma API para um job diário agendado, não para dashboard em tempo real. E converta o fuso antes de cruzar com o GA4, senão o “dia” das duas ferramentas não bate.
Clarity em aplicativos: os SDKs mobile
O Clarity não é só web. Há SDKs para Android, iOS, React Native, Cordova, Ionic e Flutter, e integrações com Amplitude, Firebase, Mixpanel e Sentry. Atenção a quem usa Flutter: Smart Events, Funis e Components ainda não são suportados nesse SDK.
Os erros que mais aparecem
- Script instalado no código e também pelo GTM, duplicando sessões.
- Cookie ligado por padrão com banner de consentimento no site: o banner promete uma coisa e a ferramenta faz outra.
- Nenhum evento personalizado: 50 mil gravações e nenhum jeito de filtrar quem chegou ao checkout.
- Campos sensíveis sem mascaramento.
- Cruzar dados exportados com o GA4 sem ajustar o fuso UTC.
Perguntas frequentes sobre Microsoft Clarity
O Microsoft Clarity é gratuito?
Sim. A ferramenta é gratuita, e as APIs client-side também não têm custo.
Clarity substitui o GA4?
Não. O GA4 mede volume, aquisição e conversão; o Clarity mostra o comportamento dentro da página. Os dois se complementam e têm integração nativa.
Como instalar o Clarity pelo Google Tag Manager?
Adicione o template oficial da Microsoft pela galeria de modelos da comunidade, informe o Project ID e configure o acionador condicionado ao consentimento.
O Clarity funciona sem cookies?
Em modo limitado: sem consentimento, cada pageview recebe um ID próprio e a jornada entre páginas não é conectada.
Qual a diferença entre evento e tag customizada no Clarity?
O evento marca uma ação que aconteceu (clicou, errou, enviou). A tag descreve um contexto da sessão (tipo de cliente, variante de teste, plano). Evento é verbo; tag é adjetivo.
Dá para usar o Clarity em aplicativo?
Sim, com os SDKs para Android, iOS, React Native, Cordova/Ionic e Flutter.