Como integrar o Mixpanel da forma correta: melhores práticas e erros a evitar

Depois de implementar o Mixpanel com mais de 80 clientes na América Latina, reunimos os aprendizados que mais importam: planejamento, arquitetura de ingestão, identificação de usuários e o tracking server-side que a maioria dos times faz errado.

Este guia é um complemento à documentação oficial do Mixpanel —por favor leia também (link). Aqui compartilhamos o que aprendemos depois de implementar o Mixpanel com mais de 80 clientes na América Latina: como se orientar, quais decisões evitam erros caros, e onde a maioria dos times trava.

Planejamento antes da implementação

O erro mais comum que vemos: o time técnico começa a integrar e trackear eventos sem ter passado por uma etapa de planejamento. Pular essa etapa sempre cobra o preço: tracking plans inconsistentes, métricas que não respondem às perguntas do negócio, e meses de retrabalho.

Na etapa de planejamento definimos, nesta ordem:

— Quais perguntas de negócio e casos de uso queremos resolver com o Mixpanel.

— A partir dessas perguntas, quais métricas precisamos conseguir construir para respondê-las.

— A partir dessas métricas, quais eventos, propriedades de evento e propriedades de usuário precisamos trackear.

Tudo isso fica documentado em um Tracking Plan, que depois o time técnico usa como guia para implementar cada evento. Escrevemos um guia detalhado com frameworks e aprendizados para essa etapa —recomendamos segui-lo.

Eventos e propriedades de evento

Eventos

Um evento é uma interação entre o usuário e seu produto que decidimos trackear. Todo evento tem um nome, um timestamp, e está atrelado a um usuário.

Por exemplo, para trackear quando um usuário compra um café no seu app, os devs precisam adicionar esta linha onde a ação é executada:

mixpanel.track('Purchased Item');

Este snippet está em JavaScript; o evento pode ser trackeado em diferentes linguagens dependendo das tecnologias que seu time usa.

Propriedades de evento

Opcionalmente, eventos podem ter propriedades que descrevem a ação do usuário com mais profundidade. Por exemplo, se o café custou USD 2,50:

mixpanel.track('Purchased Item', {
'item name': 'coffee',
'price': 2.50,
'currency': 'usd'
});

Arquitetura de ingestão de dados

Há vários métodos para enviar eventos ao Mixpanel, e o normal é combinar mais de um. Qual escolher depende dos casos de uso a resolver e da tecnologia disponível no seu time.

A arquitetura mais comum

Tracking client-side:

— Apps: trackeamos eventos de usuários em apps nativos (Android, iOS, React Native, Flutter).

— Website: trackeamos eventos e page views no site (JavaScript).

Tracking server-side:

— Backend: enviamos eventos dos nossos servidores (Node, Python, etc.). Geralmente é data transacional (Purchase, Transaction) ou de criação de conta (User Sign Up).

Arquiteturas mais avançadas

CDP: se seus dados de eventos já estão em uma Customer Data Platform (Segment, Rudderstack), você pode conectar o Mixpanel direto. Nesse caso, este guia não se aplica.

Ferramentas externas: você pode conectar o Mixpanel com ferramentas de marketing (OneSignal, Braze), CRMs (Salesforce, HubSpot), ou ferramentas de A/B testing (VWO, Optimizely) para importar dados de campanhas, clientes ou experimentos.

Data Warehouse: você pode conectar e sincronizar o Mixpanel com seu warehouse (BigQuery, Snowflake, Azure). Por exemplo, se os eventos do backend já estão no BigQuery, você pode sincronizar o Mixpanel com uma tabela em tempo real. Também é possível enriquecer com dados não-evento —marketing ad data, CRM data, etc. (docs).

Proxy client-side: dá para adicionar um proxy server entre o frontend e o Mixpanel para ganhar controle sobre os eventos do client. Detalhamos isso no final.

User identification (onde a maioria das implementações quebra)

Atenção máxima aqui. É onde a maior parte das implementações de Mixpanel desmorona.

O Mixpanel tem dois conceitos-chave: eventos e usuários. E há vários casos de uso que você quer resolver bem desde o primeiro dia:

— Um usuário pode usar seu produto anonimamente antes de criar conta.

— Depois ele se cadastra.

— Pode logar de múltiplos dispositivos (celular, notebook pessoal, notebook do trabalho).

— Pode disparar eventos de diferentes fontes (client side, server side, plataforma de marketing).

— Vários usuários podem logar no mesmo dispositivo.

Como o Mixpanel identifica usuários

Quando um usuário abre seu site ou app pela primeira vez (client side), o Mixpanel atribui um ID aleatório com o formato $device:13bbf7943e584-0885c2531-5c793977-3e8000-13bbf7943e64cf e armazena no campo $distinct_id. Esse $distinct_id é persistido no local storage do cliente (cookies em web, local storage em mobile).

Quando esse usuário dispara um evento (por exemplo 'Add to Cart'), o Mixpanel busca o $distinct_id no local storage e atrela o evento a esse ID. Por enquanto, o do usuário anônimo.

Nunca force nem envie um $user_id em eventos client-side. O SDK cuida disso nativamente.

Quando o usuário se cadastra ou faz log in, os devs do client side precisam chamar o identify com o user_id que usam internamente:

mixpanel.identify('<user_id>')

Boa prática: use um identificador que não mude no tempo e seja único por usuário. A maioria dos times já tem um —a chave primária com que identificam usuários no banco.

Ao fazer o identify call, o Mixpanel combina a atividade do usuário anônimo e do identificado no mesmo perfil. Se você estiver em Simplified ID Management, esse novo user_id passa a ser o canônico.

E se o usuário tem múltiplos dispositivos?

Imagine que o mesmo usuário abre o app de outro device e navega anonimamente. O SDK client-side cria um novo $distinct_id ($device:xxx-yyy...), e todos os eventos anônimos ficam atrelados a esse ID.

Quando o usuário faz log in nesse segundo dispositivo com o mesmo user_id de antes, o identify call combina os eventos dos dois perfis anônimos no mesmo perfil de usuário.

E se o mesmo dispositivo é usado por vários usuários?

Para evitar que o próximo usuário que logar no mesmo dispositivo herde a atividade anônima do usuário anterior, é preciso chamar o reset no log-out:

mixpanel.reset()

Isso faz o client-side criar um novo $distinct_id para o próximo usuário anônimo. Quando esse usuário se cadastrar ou logar, os eventos dele ficam corretamente atrelados ao perfil dele.

Tip-chave de user identification

Toda vez que fizer um identify call, mande também o $user_id como user property. Isso vai salvar horas de QA e debugging mais adiante.

Docs do Mixpanel client-side: JavaScript, React Native, Android, iOS.

Eventos server-side

Regra de ouro: sempre que um evento puder ser trackeado do servidor, trackeie do servidor.

Eventos client-side são menos confiáveis que os server-side. Alguns problemas típicos:

— Na web, ad blockers podem impedir o Mixpanel de gravar nos cookies, e esses eventos nunca são trackeados.

— Em web e mobile, problemas de conexão podem fazer o usuário clicar várias vezes no mesmo botão e disparar o mesmo evento múltiplas vezes.

Eventos transacionais (Purchase) e de criação de conta (Sign Up) geralmente rodam no backend. Sente com esse time, identifique quais eventos são deles, e documente no Tracking Plan que eles são responsáveis pelo tracking.

Como trackeio um evento server-side?

Você precisa indicar quem fez o evento especificando o $user_id:

mixpanel.track('Purchase', {
$user_id: 'Charlie',
price: 2.50
});

Em 99,99% dos casos, eventos server-side são enviados para usuários que já foram identificados pelo client-side.

O fluxo end-to-end normal

1. O usuário abre o app ou o site.

2. O SDK client-side cria um usuário anônimo com $device:xxx.

3. Qualquer evento disparado antes da identificação fica atrelado a esse perfil anônimo.

4. O usuário se cadastra. O client-side chama mixpanel.identify('<user_id>') e envia o user_id também como user property com mixpanel.people.set({ 'User ID': '<user_id>' }).

5. O Mixpanel combina o perfil anônimo com o identificado e guarda o $distinct_id no local storage.

6. O usuário dispara um evento client-side (por exemplo 'Add to Cart'). O client-side chama mixpanel.track('Add to Cart'); o Mixpanel pega o $distinct_id do local storage e registra o evento.

7. O usuário finaliza uma compra. O server-side registra o evento explicitando o $user_id:

mixpanel.track('Purchase', {
$user_id: '<user_id>',
price: <price>
});

O Mixpanel guarda esse evento no mesmo perfil que já contém os eventos client-side.

Edge cases para ficar de olho

O que acontece se eu trackear um evento server-side antes de o usuário ter sido identificado no client? O Mixpanel cria um novo perfil com o $distinct_id do evento server-side. Isso duplica perfis (um anônimo + um identificado). Quando o identify call do client-side rodar, os perfis são combinados. Revise esse cenário —raramente é o comportamento esperado.

E se eu enviar um evento server-side sem usuário atribuído? Ele é atrelado a um perfil com $user_id null. Geralmente é bug de implementação. Há alguns casos válidos —importar Ad Spend, por exemplo, não está atrelado a um usuário específico.

Posso trackear eventos server-side para usuários anônimos? Não recomendamos, e em mais de 50 implementações nunca tivemos um caso de uso que justificasse. Se precisar, dá para usar get_distinct_id no client para pegar o $distinct_id do usuário anônimo e enviá-lo como $device_id no evento server-side (removendo o prefixo 'device:'). Mas antes confirme se você realmente precisa disso.

Docs do Mixpanel server-side: Python, Node.js, Ruby.

Proxy server: dá para resolver os problemas do client-side?

Sim. Implementando um proxy server entre os tracks do client-side e o Mixpanel. A ideia: seu frontend manda os eventos para o seu próprio servidor, e seu servidor reenvia para o Mixpanel.

Coisas para considerar:

Como você não estará usando o SDK nativo do client-side, vai precisar reproduzir a lógica dele e fazer um QA mais detalhado. Três pontos em particular que o SDK nativo resolve sozinho e que você vai precisar replicar:

— IP: o Mixpanel usa o IP para enriquecer a geolocalização (country, city, region). Provavelmente vai precisar capturá-lo no frontend e reenviar. Docs.

— UTM Tags: o SDK nativo anexa as UTMs em todos os eventos. Você vai precisar capturá-las e reenviá-las. Docs.

— Mixpanel metadata: o SDK pega propriedades nativas do client-side (browser, device, OS, etc.). Garanta que você captura essas propriedades e as envia via proxy.

Encerrando

Se você chegou até aqui, já tem quase tudo o que precisa para a sua implementação de Mixpanel não quebrar nos primeiros três meses. Planejamento, user identification e a decisão client vs server são os três lugares onde mais vemos times quebrarem —e os três são evitáveis.

Se quiser que a gente revise sua implementação ou te acompanhe em uma migração, fala com a gente.