MIXPANEL - Event Tracking e Product Analytics

O que é este Node?

O MIXPANEL é o node responsável por enviar eventos de rastreamento para o Mixpanel, uma plataforma especializada em análise de produto e comportamento de usuários com foco em cohorts, funnels e retention.

Por que este Node existe?

Mixpanel oferece análise de produto mais profunda que ferramentas tradicionais. O MIXPANEL existe para:

Product Analytics: Rastreia como usuários realmente usam seu produto
Análise de Cohorts: Agrupa usuários por comportamento e rastreia retenção
Funnels detalhados: Analisa onde usuários abandonam processos
User Properties: Armazena atributos de usuários para segmentação

Como funciona internamente?

Quando o MIXPANEL é executado, o sistema:

Valida token: Verifica se MIXPANEL_TOKEN está configurado
Prepara payload: Cria evento com distinct_id, propriedades e timestamp
Codifica em Base64: Mixpanel exige dados em base64
Envia para API: POST para https://api.mixpanel.com/track/
Se erro de config: Retorna erro de token ausente
Se sucesso: Confirma envio do evento

Código interno (analytics-executor.service.ts:286-326):

private async executeMixpanel(operation: string, eventName: string, properties: any, userId: string, context: any): Promise<any> {
  const token = process.env.MIXPANEL_TOKEN;

  if (!token) {
    throw new Error('Mixpanel token not configured');
  }

  const payload = {
    event: eventName,
    properties: {
      ...properties,
      token: token,
      distinct_id: userId || this.generateDistinctId(),
      time: Date.now(),
      $insert_id: this.generateInsertId()
    }
  };

  try {
    const encodedData = Buffer.from(JSON.stringify(payload)).toString('base64');

    await firstValueFrom(
      this.httpService.post('https://api.mixpanel.com/track/', `data=${encodedData}`, {
        headers: {
          'Content-Type': 'application/x-www-form-urlencoded'
        }
      })
    );

    return {
      success: true,
      action: 'mixpanel_event_sent',
      provider: 'mixpanel',
      eventName: eventName,
      properties: properties,
      timestamp: new Date().toISOString()
    };
  } catch (error) {
    throw new Error(`Mixpanel tracking failed: ${error.message}`);
  }
}

Quando você DEVE usar este Node?

Use MIXPANEL sempre que precisar de análise de produto e comportamento:

Casos de uso

Análise de Feature: "Quantos usuários usam feature X?"
Retenção de Usuários: "Usuários voltam após 7 dias?"
Funnels de Conversão: "Onde usuários abandonam o onboarding?"
A/B Testing: "Variante A ou B tem mais conversão?"
User Segmentation: "Usuários premium vs free"

Quando NÃO usar MIXPANEL

SEO/Marketing: Use GOOGLE_ANALYTICS para marketing attribution
Hub centralizado: Use SEGMENT para enviar para múltiplas plataformas
Session Replay: Use HOTJAR ou FULLSTORY

Parâmetros Detalhados

provider (string, obrigatório)

O que é: Define o provedor de analytics. Para Mixpanel, use "mixpanel".

Flow completo para testar:

{
  "name": "Teste Mixpanel - Provider",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "analytics_1",
      "type": "analytics",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Rastrear com Mixpanel",
        "parameters": {
          "provider": "mixpanel",
          "eventName": "Feature Used",
          "properties": {
            "feature_name": "AI Assistant",
            "feature_category": "Automation"
          }
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Confirmar",
        "parameters": {
          "message": "✅ Evento rastreado no Mixpanel!"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 700, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "analytics_1" },
    { "source": "analytics_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Teste: Execute o flow. Verifique em Mixpanel > Events se o evento "Feature Used" aparece.

eventName (string, obrigatório)

O que é: Nome do evento a ser rastreado. Use nomes descritivos em CamelCase ou snake_case.

Flow completo para testar:

{
  "name": "Teste Mixpanel - Event Name",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "analytics_1",
      "type": "analytics",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Rastrear Signup",
        "parameters": {
          "provider": "mixpanel",
          "eventName": "User Signed Up",
          "properties": {
            "signup_method": "whatsapp",
            "plan": "free",
            "source": "organic"
          }
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Confirmar",
        "parameters": {
          "message": "🎉 Cadastro rastreado!"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 700, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "analytics_1" },
    { "source": "analytics_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Teste: Verifique em Mixpanel > Events > "User Signed Up" para ver detalhes.

properties (object, opcional)

O que é: Propriedades customizadas do evento para análise e segmentação.

Flow completo para testar:

{
  "name": "Teste Mixpanel - Properties",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "analytics_1",
      "type": "analytics",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Evento Detalhado",
        "parameters": {
          "provider": "mixpanel",
          "eventName": "Purchase Completed",
          "properties": {
            "product_id": "PROD_123",
            "product_name": "Curso TypeScript",
            "price": 297.00,
            "currency": "BRL",
            "payment_method": "credit_card",
            "discount_applied": true,
            "discount_code": "SUMMER25",
            "items_count": 1,
            "category": "Education"
          }
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Confirmar",
        "parameters": {
          "message": "💰 Compra rastreada com 9 propriedades!"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 700, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "analytics_1" },
    { "source": "analytics_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Teste: Confira em Mixpanel se todas as 9 propriedades foram capturadas corretamente.

userId (string, opcional)

O que é: Identificador único do usuário (distinct_id no Mixpanel) para análise de cohort.

Flow completo para testar:

{
  "name": "Teste Mixpanel - User ID",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "input_1",
      "type": "input",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Pedir Email",
        "parameters": {
          "message": "Qual seu email?",
          "variable": "user_email"
        }
      }
    },
    {
      "id": "analytics_1",
      "type": "analytics",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Rastrear Login",
        "parameters": {
          "provider": "mixpanel",
          "eventName": "User Logged In",
          "userId": "{{user_email}}",
          "properties": {
            "login_method": "email_password",
            "device_type": "mobile"
          }
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Confirmar",
        "parameters": {
          "message": "✅ Login rastreado para: {{user_email}}"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 900, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "input_1" },
    { "source": "input_1", "target": "analytics_1" },
    { "source": "analytics_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Teste: Digite seu email. No Mixpanel, veja que todos os eventos ficam vinculados ao mesmo distinct_id.

Parâmetros

Campo	Tipo	Obrigatório	Descrição
provider	string	Sim	Deve ser `"mixpanel"`
eventName	string	Sim	Nome do evento (ex: "User Signed Up")
properties	object	Não	Propriedades customizadas do evento
userId	string	Não	distinct_id do usuário no Mixpanel
operation	string	Não	Tipo de operação (padrão: "track")

Configuração Necessária

Variáveis de Ambiente

Adicione no arquivo .env:

MIXPANEL_TOKEN=seu_project_token_aqui

Como obter o token:

Acesse Mixpanel
Vá em Settings > Project Settings
Copie o Project Token
Cole no .env como MIXPANEL_TOKEN

Exemplo 1: Rastrear Jornada de Onboarding

Objetivo: Monitorar cada etapa do onboarding para identificar drop-off.

JSON para Importar

{
  "name": "Mixpanel - Onboarding Funnel",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "analytics_1",
      "type": "analytics",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Etapa 1: Iniciou",
        "parameters": {
          "provider": "mixpanel",
          "eventName": "Onboarding Started",
          "properties": {
            "step": 1,
            "step_name": "welcome"
          }
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Boas-vindas",
        "parameters": {
          "message": "👋 Bem-vindo! Vamos começar seu cadastro."
        }
      }
    },
    {
      "id": "input_1",
      "type": "input",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Pedir Nome",
        "parameters": {
          "message": "Qual é o seu nome?",
          "variable": "nome"
        }
      }
    },
    {
      "id": "analytics_2",
      "type": "analytics",
      "position": { "x": 900, "y": 100 },
      "data": {
        "label": "Etapa 2: Nome",
        "parameters": {
          "provider": "mixpanel",
          "eventName": "Onboarding Step Completed",
          "properties": {
            "step": 2,
            "step_name": "name_provided"
          }
        }
      }
    },
    {
      "id": "input_2",
      "type": "input",
      "position": { "x": 1100, "y": 100 },
      "data": {
        "label": "Pedir Email",
        "parameters": {
          "message": "Qual seu email?",
          "variable": "email"
        }
      }
    },
    {
      "id": "analytics_3",
      "type": "analytics",
      "position": { "x": 1300, "y": 100 },
      "data": {
        "label": "Etapa 3: Completo",
        "parameters": {
          "provider": "mixpanel",
          "eventName": "Onboarding Completed",
          "userId": "{{email}}",
          "properties": {
            "step": 3,
            "step_name": "completed",
            "user_name": "{{nome}}",
            "total_time_seconds": 120
          }
        }
      }
    },
    {
      "id": "message_2",
      "type": "message",
      "position": { "x": 1500, "y": 100 },
      "data": {
        "label": "Sucesso",
        "parameters": {
          "message": "✅ Onboarding completo!\n\n📊 Jornada rastreada no Mixpanel."
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 1700, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "analytics_1" },
    { "source": "analytics_1", "target": "message_1" },
    { "source": "message_1", "target": "input_1" },
    { "source": "input_1", "target": "analytics_2" },
    { "source": "analytics_2", "target": "input_2" },
    { "source": "input_2", "target": "analytics_3" },
    { "source": "analytics_3", "target": "message_2" },
    { "source": "message_2", "target": "end_1" }
  ]
}

Saída esperada:

Sistema: 👋 Bem-vindo! Vamos começar seu cadastro.
Sistema: Qual é o seu nome?
Usuário: João
Sistema: Qual seu email?
Usuário: joao@email.com
Sistema: ✅ Onboarding completo! Jornada rastreada no Mixpanel.

Exemplo 2: Rastrear Feature Adoption

Objetivo: Medir quantos usuários adotam uma nova feature.

JSON para Importar

{
  "name": "Mixpanel - Feature Adoption",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Oferecer Feature",
        "parameters": {
          "message": "🚀 Nova feature disponível!\n\nAssistente com processamento avançado.\n\nDeseja experimentar?"
        }
      }
    },
    {
      "id": "input_1",
      "type": "input",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Capturar Resposta",
        "parameters": {
          "message": "Digite SIM ou NÃO",
          "variable": "resposta"
        }
      }
    },
    {
      "id": "condition_1",
      "type": "condition",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Verificar Resposta",
        "parameters": {
          "variable": "resposta",
          "operator": "equals",
          "value": "SIM"
        }
      }
    },
    {
      "id": "analytics_1",
      "type": "analytics",
      "position": { "x": 900, "y": 50 },
      "data": {
        "label": "Feature Aceita",
        "parameters": {
          "provider": "mixpanel",
          "eventName": "Feature Adopted",
          "properties": {
            "feature_name": "AI Assistant Pro",
            "adoption_method": "in_app_prompt",
            "user_segment": "active_users"
          }
        }
      }
    },
    {
      "id": "analytics_2",
      "type": "analytics",
      "position": { "x": 900, "y": 150 },
      "data": {
        "label": "Feature Rejeitada",
        "parameters": {
          "provider": "mixpanel",
          "eventName": "Feature Rejected",
          "properties": {
            "feature_name": "AI Assistant Pro",
            "rejection_reason": "user_declined"
          }
        }
      }
    },
    {
      "id": "message_2",
      "type": "message",
      "position": { "x": 1100, "y": 100 },
      "data": {
        "label": "Confirmar",
        "parameters": {
          "message": "📊 Decisão rastreada no Mixpanel!"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 1300, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "message_1" },
    { "source": "message_1", "target": "input_1" },
    { "source": "input_1", "target": "condition_1" },
    { "source": "condition_1", "target": "analytics_1", "label": "true" },
    { "source": "condition_1", "target": "analytics_2", "label": "false" },
    { "source": "analytics_1", "target": "message_2" },
    { "source": "analytics_2", "target": "message_2" },
    { "source": "message_2", "target": "end_1" }
  ]
}

Saída esperada:

Sistema: 🚀 Nova feature disponível! Assistente com processamento avançado. Deseja experimentar?
Usuário: SIM
Sistema: 📊 Decisão rastreada no Mixpanel!

Resposta do Node

{
  "success": true,
  "action": "mixpanel_event_sent",
  "provider": "mixpanel",
  "eventName": "Feature Adopted",
  "properties": {
    "feature_name": "AI Assistant Pro",
    "adoption_method": "in_app_prompt"
  },
  "timestamp": "2025-01-15T10:30:00.000Z"
}

Tipos de Análise no Mixpanel

Funnels

Rastreie conversão em múltiplas etapas:

Onboarding Started → Step Completed → Onboarding Completed

Cohorts

Agrupe usuários por comportamento: - Usuários que compraram nos últimos 30 dias - Usuários que nunca usaram feature X

Retention

Meça quantos usuários voltam: - Day 1, Day 7, Day 30 retention

Flows

Visualize caminhos reais dos usuários pelo produto.

Boas Práticas

✅ SIM:

Use nomes de eventos consistentes (CamelCase ou snake_case)
Inclua propriedades relevantes para segmentação
Defina userId (distinct_id) para rastrear jornada completa
Use people properties para atributos permanentes do usuário
Teste eventos em Mixpanel Live View antes de produção

❌ NÃO:

Não envie dados sensíveis (senhas, CPF, cartões)
Não use nomes de eventos muito genéricos ("click", "event")
Não misture naming conventions (escolha uma e mantenha)
Não esqueça de configurar MIXPANEL_TOKEN

Dicas

💡 Dica 1: Use Mixpanel Live View para ver eventos chegando em tempo real durante testes

💡 Dica 2: Crie funnels personalizados em Mixpanel > Funnels para analisar conversão

💡 Dica 3: Configure cohorts para segmentar usuários por comportamento específico

💡 Dica 4: Use $insert_id (gerado automaticamente) para prevenir duplicatas

💡 Dica 5: Combine Mixpanel com SEGMENT para enviar eventos para múltiplas plataformas simultaneamente

Próximo Node

→ SEGMENT - Hub de analytics que envia para múltiplas plataformas → AMPLITUDE - Alternativa ao Mixpanel com foco em product analytics → HEAP - Auto-capture analytics sem código