A conexão com o Microsoft Clarity é feita por um token de API gerado no próprio projeto, na área de Data Export. Nenhuma senha de usuário é usada.

Antes de começar

• Tenha acesso de administrador ao projeto no Clarity (clarity.microsoft.com) — só administradores do projeto conseguem gerar o token.
• Gere o token no projeto: Settings → Data Export → Generate new API token. Dê ao token o nome toca: assim você identifica de quem ele é e pode revogá-lo depois sem derrubar outras integrações do projeto.
• Saiba os limites da API do Clarity: ela cobre apenas as últimas 72 horas de dados e concede 10 consultas por projeto por dia.

Passo a passo

1. Acesse Configurações → Integrações na Toca.
2. Localize o card Microsoft Clarity e clique no botão de conexão.
3. Preencha o único campo:
   • api_token — o API token do projeto, gerado em Settings → Data Export.
4. Salve. O card fica marcado como conectado e a Toca já consegue consultar o projeto.

O que a Toca acessa

Com a conexão ativa, a Toca lê o comportamento no site nas últimas 24, 48 ou 72 horas: sessões, usuários, páginas mais vistas, origem do tráfego, dispositivo e os sinais de fricção do Clarity (rage click, dead click, scroll excessivo, quickback e erro de script). A integração é somente de leitura: a Toca não altera nada no Clarity.

Dois limites da própria API valem a pena conhecer: a janela máxima é de 72 horas — perguntas sobre mês, trimestre ou ano não têm resposta pelo Clarity e são respondidas por outras integrações conectadas (GA4, por exemplo) — e são 10 consultas por dia no projeto inteiro. Quando as consultas do dia acabam, a Toca avisa; o saldo volta na virada do dia (em UTC), então algumas perguntas precisam esperar o dia seguinte.

Manutenção da conexão

O token do Clarity é estático e não tem expiração documentada: a conexão permanece ativa até você revogar o token no projeto ou desconectar a integração na Toca. Se o token for revogado no Clarity, o card em Configurações → Integrações passa a indicar que a conexão precisa ser refeita — gere um token novo em Settings → Data Export e reconecte.

Problemas comuns

• Erro de autenticação nas consultas — o token pode ter sido revogado ou colado com espaços extras. Gere um token novo em Settings → Data Export e atualize a conexão.
• "As consultas do dia acabaram" — é a cota da API do Clarity (10 por projeto por dia), não um problema da conexão. O saldo volta na virada do dia em UTC.
• Pergunta de mês ou ano sem resposta pelo Clarity — a API só cobre as últimas 72 horas. Para histórico, use outra integração conectada, como o GA4.
• Não consigo gerar o token — apenas administradores do projeto veem a opção em Settings → Data Export. Peça a um administrador para gerar ou para promover seu acesso.
• Lista de páginas ou origens parece incompleta — a API corta em 1.000 linhas por métrica, sem paginação. A Toca sinaliza quando a lista bateu nesse teto.