BK-261 - Clarity: identify enriquecido + atalhos úteis no detalhe do cliente

Objetivo

• enriquecer a instrumentação atual do Microsoft Clarity no site
• melhorar o valor operacional do clarity-tab em admin/modulos/clientes/detalhe.php
• preparar a base para rastrear melhor abandono de checkout e sessão por cliente

Motivação

• hoje o site já envia custom-id = cliente_id, mas ainda deixa vazios custom-session-id e custom-page-id
• o clarity-tab atual mostra visitor_id, porém a API pública usada no proxy não lista gravações por user_id
• a doc oficial atual do Clarity reforça o uso de:
• identify(custom-id, custom-session-id, custom-page-id, friendly-name)
• set(key, value)
• event(name)
• upgrade(reason)

Escopo da rodada

• meta-analytics.php
• checkout_pix.php
• js/checkout_pix.js
• admin/modulos/clientes/detalhe.php
• api/clarity_proxy.php

Resultado esperado

• cliente logado envia custom-id, custom-session-id, custom-page-id e friendly-name
• checkout emite contexto útil para análise operacional no Clarity
• aba do cliente fica mais acionável para abrir o projeto certo e copiar os identificadores relevantes rapidamente

Implementação - 2026-04-12 04:04 -03

• meta-analytics.php
• clarity("identify", ...) foi enriquecido para enviar:
• custom-id = cliente_id
• custom-session-id = visitor_id
• custom-page-id = page:<rota-normalizada>
• friendly-name = nome/identificação curta do cliente
• tags adicionais:
• user_id
• visitor_id
• segment
• login_state
• page_id
• checkout_pix.php
• passou a expor window.RNT_CLARITY_CHECKOUT com:
• pedidoId
• tipo
• clienteId
• eventoId
• sessaoData
• quantidade
• totalPedido
• js/checkout_pix.js
• adicionados set/event/upgrade para o fluxo do checkout
• eventos emitidos:
• checkout_pix_open
• checkout_select_pix
• checkout_select_card
• checkout_select_boleto
• checkout_wallet_mode_click
• checkout_wallet_credit_submit
• checkout_pix_submit
• checkout_card_submit
• checkout_pix_generated
• checkout_pix_error
• checkout_card_success
• checkout_card_pending
• checkout_card_warning
• checkout_card_error
• checkout_wallet_credit_success
• admin/modulos/clientes/detalhe.php
• clarity-tab recebeu botão para abrir recordings
• tabela de visitor_id recebeu coluna de ações com:
• copiar visitor_id
• abrir recordings
• texto operacional da aba foi ajustado para orientar uso conjunto de Custom User ID e visitor_id
• api/clarity_proxy.php
• hint do 501 foi alinhado à estratégia atual baseada em custom identifiers + visitor ids

Captura do Clarity User ID - 2026-04-12 04:52 -03

• meta-analytics.php
• o site agora tenta capturar o retorno do clarity("identify", ...)
• quando houver Promise resolvida, envia ao backend:
• clarity_id
• clarity_session_id
• clarity_page_id
• clarity_user_hint
• visitor_id
• action.php
• nova action save_clarity_identity
• persistência ampliada em clarity_identity_links para:
• clarity_id
• clarity_session_id
• clarity_page_id
• clarity_user_hint
• admin/modulos/clientes/detalhe.php
• a tabela do clarity-tab agora mostra Clarity User ID
• a tabela também expõe Clarity Session, Clarity Page e User Hint
• quando houver clarity_id, a linha passa a renderizar link direto de impressions
• https://clarity.microsoft.com/projects/view/tymtbjxe8i/impressions?UserId=is%3B<clarity_id>&date=Last%203%20days
• o topo da aba passa a oferecer um CTA direto de impressions quando já existir clarity_id principal para o cliente

Hardening do bootstrap do identify - 2026-04-12 05:24 -03

• causa provável do clarity_id ainda vazio na base:
• o primeiro clarity("identify", ...) estava sendo disparado cedo demais, ainda no stub enfileirador do snippet do Clarity
• nesse estado, o retorno útil do identify não chegava ao código que persistia o clarity_id
• correção aplicada:
• o frontend passou a reexecutar o identify após load, com retries curtos até o runtime real do Clarity devolver Promise ou payload útil
• o envio ao backend agora deduplica o fingerprint do identity para evitar gravações redundantes
• ajuste operacional do painel:
• a aba do cliente deixou de tratar o cliente_id do RNT como “Custom User ID” principal
• o destaque visual agora prioriza o Clarity User ID capturado e o botão de copiar esse valor

Reforço via checkout - 2026-04-12 05:30 -03

• meta-analytics.php
• quando o identify retorna payload útil, o frontend agora guarda também capturedIdentity em window.RNT_CLARITY_CONTEXT
• js/checkout_pix.js
• cada checkout_flow_ping passou a anexar clarity_id, clarity_session_id, clarity_page_id e clarity_user_hint quando esses valores já estiverem capturados no navegador
• action.php
• checkout_flow_ping agora tenta reaproveitar esses campos para reforçar clarity_identity_links usando o cliente_id do próprio pedido
• isso melhora a chance de amarrar cliente, pedido e gravação mesmo quando a sessão abandona cedo no checkout

Fallback oficial via cookies do Clarity - 2026-04-12 05:43 -03

• evidência oficial usada:
• a documentação de cookies do Clarity informa que _clck persiste o Clarity User ID
• _clsk conecta múltiplas páginas a uma mesma sessão
• correção aplicada em action.php:
• o backend agora lê _clck e _clsk diretamente de $_COOKIE
• usa o primeiro segmento do cookie como fallback sanitizado para clarity_id e clarity_session_id
• rnt_link_visitor_to_cliente passou a gravar esses valores quando login/cadastro já chegam com os cookies do Clarity
• rnt_clarity_identity_capture e rnt_checkout_flow_log também reaproveitam esse fallback
• efeito esperado:
• a captura do Clarity User ID deixa de depender do retorno do identify() no frontend
• novos logins, cadastros e eventos de checkout devem começar a popular clarity_identity_links

Validações executadas

• php -l meta-analytics.php
• php -l checkout_pix.php
• node --check js/checkout_pix.js
• php -l admin/modulos/clientes/detalhe.php
• php -l api/clarity_proxy.php
• php -l action.php
• smoke test local do parser server-side:
• _clck=yj300g|... => yj300g
• _clsk=sess_abc123|... => sess_abc123

Observação

• esta rodada melhora fortemente a encontrabilidade operacional no Clarity, mas ainda não cria um endpoint garantido de gravações por cliente na API pública