Ponte com PostHog, Mixpanel & Amplitude

A sua ferramenta de análise de produto mostra o que aconteceu. O MousePlayer mostra por quê. Esta ponte conecta as duas nos dois sentidos, de modo que uma desistência no funil fica a um clique da gravação que a explica.

1. O problema: números sem rosto

A análise de produto entrega um funil: 1.000 usuários chegaram ao checkout, 620 desistiram. É a medição precisa de um problema que você ainda não consegue ver. Assistir a algumas dessas 620 gravações costuma responder a pergunta em minutos — mas só se for possível ir do gráfico até as sessões certas sem exportar IDs e procurar à mão.

A ponte de análise de produto elimina essa lacuna. Ela roda dentro do mp.js e liga os dois sistemas automaticamente:

  • Saída: todo evento registrado pela sua ferramenta de análise leva a propriedade mouseplayer_session_url. Abra qualquer evento, clique no link e assista à sessão.
  • Entrada: o distinct_id do visitante é lido de volta e armazenado na sessão do MousePlayer, de modo que as gravações podem ser buscadas pela mesma identidade que você já usa no PostHog, no Mixpanel ou no Amplitude.

Nenhum código necessário. A ponte detecta sozinha o SDK de análise. Você não chama nenhuma função do MousePlayer e não precisa mudar a forma como rastreia eventos.

2. Ativação

Método A: painel (sem código)

  1. Abra o seu projeto e vá até a aba Integrações.
  2. Mude Ponte com PostHog, Mixpanel & Amplitude para ON.
  3. Selecione a plataforma que você usa. As alterações são salvas automaticamente.

A configuração passa a valer no próximo carregamento de página do seu site. Sessões já existentes não são afetadas retroativamente.

Método B: configuração manual do script

Se preferir fixar no código, defina os dois valores dentro de window.mp_config:

<!-- MousePlayer SDK with the Product Analytics Bridge enabled --> <script> window.mp_config = { channel: 'YOUR_CHANNEL_ID', analytics_bridge_active: true, analytics_provider: 'posthog' // 'posthog', 'mixpanel' or 'amplitude' }; </script>

3. O que acontece em cada plataforma

Cada plataforma oferece uma API diferente, por isso a ponte usa a chamada idiomática de cada uma. Você não precisa configurar nada — ela segue o provedor que você selecionou.

PlataformaSaída (URL da reprodução)Entrada (identidade)
PostHog posthog.register() — registrada como super property, portanto anexada a todos os eventos seguintes posthog.get_distinct_id()
Mixpanel mixpanel.register() — mesmo comportamento de super property mixpanel.get_distinct_id()
Amplitude setUserProperties() — definida como user property getDeviceId(), com getInstance().options.deviceId como alternativa no SDK legado

Super property vs. user property: no PostHog e no Mixpanel, a URL da reprodução é anexada aos eventos daqui para a frente; por isso, você a encontrará em todos os eventos disparados depois que a ponte é inicializada — não nos eventos já enviados antes, durante o carregamento da página.

4. Identidade: do distinct_id a uma sessão identificada

A metade de entrada é a parte que a maioria das equipes subestima. Sem ela, as sessões do MousePlayer são anônimas: você pode assisti-las, mas não consegue responder a “mostre as gravações da conta que cancelou na semana passada”.

Com a ponte ativa, o distinct_id da sua ferramenta de análise é gravado no campo custom_user_id da sessão — o mesmo campo em que a chamada manual do SDK grava:

// The manual equivalent - you do NOT need this when the bridge is active mp('set', { user_id: 'your-internal-id' });

Se você já chama mp('set') por conta própria, continue fazendo isso. Uma identidade que você informa explicitamente é a mais confiável, porque é a sua própria chave primária, e não um identificador de análise por navegador.

Nota de privacidade: só é transferido o identificador que a sua ferramenta de análise já atribuiu. Nenhum endereço de e-mail, nome ou outro campo pessoal é lido do SDK. Garanta que a sua política de privacidade cubra esse tratamento e condicione o script de rastreamento à sua ferramenta de consentimento, se o consentimento for a sua base legal.

5. Comportamento técnico

Os SDKs de análise costumam ser carregados de forma assíncrona, muitas vezes depois que o mp.js já está rodando. Uma única tentativa na inicialização falharia, portanto, na maioria dos sites reais.

  • A ponte tenta de novo a cada 1,5 segundo, até dez vezes, e para assim que os dois sentidos são concluídos.
  • Cada sentido é concluído de forma independente, por isso a URL da reprodução nunca é enviada duas vezes enquanto se espera uma identidade aparecer.
  • Se o SDK nunca aparecer, a ponte desiste silenciosamente após cerca de 15 segundos. Nada é escrito no console, e a gravação da sessão continua normalmente.
  • Identificadores com mais de 128 caracteres são ignorados em vez de truncados, para não armazenar meio identificador que nunca corresponderia a nada.

6. Como verificar se funciona

  1. Abra o seu site em uma aba normal do navegador e interaja com ele rapidamente.
  2. Na sua ferramenta de análise, abra o evento mais recente e procure a propriedade mouseplayer_session_url. Ao abri-la, você deve ir direto para a gravação.
  3. No MousePlayer, abra o explorador de usuários. Sessões que têm uma identidade mostram essa identidade no lugar do apelido gerado para o visitante.

Se nada aparecer

  • A propriedade falta em todos os eventos: verifique se o SDK de análise realmente carrega na página e se você selecionou a plataforma correspondente. Com PostHog selecionado, o Mixpanel não é lido.
  • A propriedade só aparece em eventos posteriores: isso é esperado; veja a nota na seção 3.
  • A URL está lá, mas a identidade não: o seu SDK ainda não atribuiu um distinct_id, o que é normal antes de o usuário ser identificado. Ele será capturado em um carregamento de página posterior.
  • Você está testando logado como administrador: algumas configurações excluem o tráfego interno. Tente uma janela anônima.

Todas as marcas citadas aqui pertencem aos seus respectivos proprietários. O MousePlayer não tem relação comercial com esses provedores.