Pular para conteúdo

ANALYTICS - Rastrear Eventos e Comportamento

O que é este Node?

O ANALYTICS é o node responsável por rastrear eventos e comportamento do usuário enviando dados para plataformas de analytics como Google Analytics, Mixpanel, Amplitude, Segment ou sistema customizado.

Por que este Node existe?

Entender o comportamento do usuário é fundamental para otimização. O ANALYTICS existe para:

  1. Rastreamento de eventos: Capturar ações importantes dos usuários
  2. Análise de comportamento: Entender como usuários interagem com o flow
  3. Métricas de conversão: Medir performance de funis e campanhas
  4. Integração com plataformas: Conectar com Google Analytics, Mixpanel, Amplitude, Segment
  5. Decisões baseadas em dados: Ter insights para melhorar a experiência

Como funciona internamente?

Quando o ANALYTICS é executado, o sistema:

  1. Identifica o provider (google_analytics, mixpanel, amplitude, segment, custom)
  2. Prepara os dados do evento com propriedades
  3. Formata a requisição conforme API do provider
  4. Envia para a plataforma de analytics
  5. Registra localmente para backup e análise
  6. Retorna confirmação do evento rastreado

Código interno (analytics-executor.service.ts:46-70): 

private async executeAnalytics(parameters: any, context: any): Promise<any> {
  const { provider, operation, eventName, properties, userId, sessionId } = parameters;

  this.logger.log(`📊 ANALYTICS - Provider: ${provider}, Event: ${eventName}`);

  switch (provider?.toLowerCase()) {
    case 'google_analytics':
      return this.executeGoogleAnalytics(operation, eventName, properties, userId, context);

    case 'mixpanel':
      return this.executeMixpanel(operation, eventName, properties, userId, context);

    case 'amplitude':
      return this.executeAmplitude(operation, eventName, properties, userId, context);

    case 'segment':
      return this.executeSegment(operation, eventName, properties, userId, context);

    case 'custom':
      return this.executeCustomAnalytics(operation, eventName, properties, userId, context);

    default:
      return this.executeDefaultAnalytics(eventName, properties, userId, sessionId, context);
  }
}

Quando você DEVE usar este Node?

Use ANALYTICS sempre que precisar rastrear comportamento do usuário:

Casos de uso:

  1. Funis de conversão: Rastrear etapas de cadastro, compra, etc.
  2. Eventos de negócio: Botão clicado, formulário enviado, produto visualizado
  3. Análise de campanhas: Medir eficácia de marketing
  4. A/B Testing: Rastrear variantes e conversões
  5. User journey: Mapear jornada completa do usuário
  6. Performance de features: Entender quais recursos são mais usados

Quando NÃO usar ANALYTICS:

  • Logs técnicos: Use LOGGER para debug e logs de sistema
  • Métricas de infraestrutura: Use METRIC para KPIs técnicos
  • Tracking simples: Use EVENT para eventos sem integração externa

Parâmetros Detalhados

provider (string, opcional)

O que é: Plataforma de analytics onde o evento será enviado.

Opções: google_analytics, mixpanel, amplitude, segment, custom

Padrão: Sistema padrão (armazenamento local)

Flow completo para testar Google Analytics:

{
  "name": "Teste ANALYTICS - Google Analytics",
  "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 Pageview",
        "parameters": {
          "provider": "google_analytics",
          "eventName": "page_view",
          "properties": {
            "page_title": "Home",
            "page_path": "/home"
          }
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Confirmar",
        "parameters": {
          "message": "✅ Evento enviado para Google Analytics!"
        }
      }
    },
    {
      "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: Evento será enviado para Google Analytics (requer GA_MEASUREMENT_ID e GA_API_SECRET configurados)

eventName (string, obrigatório)

O que é: Nome do evento sendo rastreado.

Flow completo para testar:

{
  "name": "Teste ANALYTICS - Event Name",
  "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": "Nome do Produto",
        "parameters": {
          "message": "Qual produto você quer ver?",
          "variable": "produto"
        }
      }
    },
    {
      "id": "analytics_1",
      "type": "analytics",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Rastrear Visualização",
        "parameters": {
          "eventName": "product_viewed",
          "properties": {
            "product_name": "{{produto}}",
            "category": "electronics"
          }
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Confirmar",
        "parameters": {
          "message": "Visualizando: {{produto}}"
        }
      }
    },
    {
      "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 "iPhone" - evento "product_viewed" será rastreado com o nome do produto

properties (object, opcional)

O que é: Propriedades adicionais do evento (dados contextuais).

Flow completo para testar:

{
  "name": "Teste ANALYTICS - Properties",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "number_1",
      "type": "number",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Valor da Compra",
        "parameters": {
          "message": "Qual o valor da compra?",
          "variable": "valor",
          "decimals": 2
        }
      }
    },
    {
      "id": "analytics_1",
      "type": "analytics",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Rastrear Compra",
        "parameters": {
          "eventName": "purchase_completed",
          "properties": {
            "value": "{{valor}}",
            "currency": "BRL",
            "payment_method": "credit_card",
            "items_count": 3
          }
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Confirmar",
        "parameters": {
          "message": "✅ Compra de R$ {{valor}} rastreada!"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 900, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "number_1" },
    { "source": "number_1", "target": "analytics_1" },
    { "source": "analytics_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Teste: Digite 150.50 - evento com valor, moeda e método de pagamento será rastreado

userId (string, opcional)

O que é: ID único do usuário para rastreamento cross-session.

Padrão: Usa context.userId automaticamente

sessionId (string, opcional)

O que é: ID da sessão atual do usuário.

Padrão: Usa context.sessionId automaticamente

operation (string, opcional)

O que é: Tipo de operação a realizar (usado por alguns providers).

Opções: track, identify, page, screen, group, alias

Parâmetros

Campo Tipo Obrigatório Descrição
provider string Não Plataforma de analytics (google_analytics, mixpanel, amplitude, segment, custom)
eventName string Sim Nome do evento a rastrear
properties object Não Propriedades adicionais do evento
userId string Não ID do usuário (padrão: context.userId)
sessionId string Não ID da sessão (padrão: context.sessionId)
operation string Não Tipo de operação (track, identify, page, etc.)

Exemplo 1: Funil de Conversão Completo

Objetivo: Rastrear todas as etapas de um funil de cadastro

JSON para Importar

{
  "name": "Funil de Cadastro com ANALYTICS",
  "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": {
          "eventName": "signup_started",
          "properties": {
            "step": 1,
            "funnel": "registration"
          }
        }
      }
    },
    {
      "id": "input_1",
      "type": "input",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Nome",
        "parameters": {
          "message": "Qual é o seu nome?",
          "variable": "nome"
        }
      }
    },
    {
      "id": "analytics_2",
      "type": "analytics",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Etapa 2 - Nome",
        "parameters": {
          "eventName": "signup_name_provided",
          "properties": {
            "step": 2,
            "funnel": "registration"
          }
        }
      }
    },
    {
      "id": "email_1",
      "type": "email",
      "position": { "x": 900, "y": 100 },
      "data": {
        "label": "Email",
        "parameters": {
          "message": "Qual é o seu email?",
          "variable": "email"
        }
      }
    },
    {
      "id": "analytics_3",
      "type": "analytics",
      "position": { "x": 1100, "y": 100 },
      "data": {
        "label": "Etapa 3 - Completo",
        "parameters": {
          "eventName": "signup_completed",
          "properties": {
            "step": 3,
            "funnel": "registration",
            "email": "{{email}}"
          }
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 1300, "y": 100 },
      "data": {
        "label": "Sucesso",
        "parameters": {
          "message": "✅ Cadastro completo, {{nome}}! Todas as etapas foram rastreadas."
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 1500, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "analytics_1" },
    { "source": "analytics_1", "target": "input_1" },
    { "source": "input_1", "target": "analytics_2" },
    { "source": "analytics_2", "target": "email_1" },
    { "source": "email_1", "target": "analytics_3" },
    { "source": "analytics_3", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Saída esperada:

Sistema: Qual é o seu nome?
Usuário: João Silva
Sistema: Qual é o seu email?
Usuário: joao@example.com
Sistema: ✅ Cadastro completo, João Silva! Todas as etapas foram rastreadas.

Eventos rastreados: 1. signup_started (step: 1) 2. signup_name_provided (step: 2) 3. signup_completed (step: 3, email: joao@example.com)

Exemplo 2: E-commerce com Múltiplos Provedores

Objetivo: Enviar eventos para Google Analytics e Mixpanel simultaneamente

JSON para Importar

{
  "name": "E-commerce Multi-Provider",
  "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": "Produto",
        "parameters": {
          "message": "Qual produto deseja?",
          "variable": "produto"
        }
      }
    },
    {
      "id": "analytics_ga",
      "type": "analytics",
      "position": { "x": 500, "y": 50 },
      "data": {
        "label": "Google Analytics",
        "parameters": {
          "provider": "google_analytics",
          "eventName": "view_item",
          "properties": {
            "item_name": "{{produto}}",
            "item_category": "products"
          }
        }
      }
    },
    {
      "id": "analytics_mp",
      "type": "analytics",
      "position": { "x": 500, "y": 150 },
      "data": {
        "label": "Mixpanel",
        "parameters": {
          "provider": "mixpanel",
          "eventName": "Product Viewed",
          "properties": {
            "product": "{{produto}}",
            "source": "whatsapp"
          }
        }
      }
    },
    {
      "id": "number_1",
      "type": "number",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Quantidade",
        "parameters": {
          "message": "Quantas unidades?",
          "variable": "quantidade",
          "min": 1
        }
      }
    },
    {
      "id": "analytics_cart_ga",
      "type": "analytics",
      "position": { "x": 900, "y": 50 },
      "data": {
        "label": "GA - Add to Cart",
        "parameters": {
          "provider": "google_analytics",
          "eventName": "add_to_cart",
          "properties": {
            "item_name": "{{produto}}",
            "quantity": "{{quantidade}}"
          }
        }
      }
    },
    {
      "id": "analytics_cart_mp",
      "type": "analytics",
      "position": { "x": 900, "y": 150 },
      "data": {
        "label": "MP - Add to Cart",
        "parameters": {
          "provider": "mixpanel",
          "eventName": "Added to Cart",
          "properties": {
            "product": "{{produto}}",
            "qty": "{{quantidade}}"
          }
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 1100, "y": 100 },
      "data": {
        "label": "Confirmar",
        "parameters": {
          "message": "✅ {{quantidade}}x {{produto}} adicionado!\n\n📊 Eventos enviados para GA e Mixpanel"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 1300, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "input_1" },
    { "source": "input_1", "target": "analytics_ga" },
    { "source": "input_1", "target": "analytics_mp" },
    { "source": "analytics_ga", "target": "number_1" },
    { "source": "analytics_mp", "target": "number_1" },
    { "source": "number_1", "target": "analytics_cart_ga" },
    { "source": "number_1", "target": "analytics_cart_mp" },
    { "source": "analytics_cart_ga", "target": "message_1" },
    { "source": "analytics_cart_mp", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Saída esperada:

Sistema: Qual produto deseja?
Usuário: iPhone 15
Sistema: Quantas unidades?
Usuário: 2
Sistema: ✅ 2x iPhone 15 adicionado!

📊 Eventos enviados para GA e Mixpanel

Exemplo 3: Rastreamento de Campanha

Objetivo: Rastrear origem e conversão de campanha de marketing

JSON para Importar

{
  "name": "Campaign Tracking",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "variable_1",
      "type": "variable",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Definir Campanha",
        "parameters": {
          "operation": "set",
          "variables": {
            "campaign_source": "whatsapp",
            "campaign_medium": "chat",
            "campaign_name": "black_friday_2025"
          }
        }
      }
    },
    {
      "id": "analytics_1",
      "type": "analytics",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Campaign Started",
        "parameters": {
          "eventName": "campaign_interaction",
          "properties": {
            "source": "{{campaign_source}}",
            "medium": "{{campaign_medium}}",
            "campaign": "{{campaign_name}}",
            "action": "started"
          }
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Oferta",
        "parameters": {
          "message": "🔥 BLACK FRIDAY!\n\n50% OFF em todos os produtos!\n\nQuer aproveitar?"
        }
      }
    },
    {
      "id": "input_1",
      "type": "input",
      "position": { "x": 900, "y": 100 },
      "data": {
        "label": "Resposta",
        "parameters": {
          "message": "Digite SIM para aproveitar:",
          "variable": "resposta"
        }
      }
    },
    {
      "id": "condition_1",
      "type": "condition",
      "position": { "x": 1100, "y": 100 },
      "data": {
        "label": "Converteu?",
        "parameters": {
          "conditions": [
            {
              "variable": "resposta",
              "operator": "equals",
              "value": "SIM"
            }
          ],
          "logic": "AND"
        }
      }
    },
    {
      "id": "analytics_converted",
      "type": "analytics",
      "position": { "x": 1300, "y": 50 },
      "data": {
        "label": "Conversão",
        "parameters": {
          "eventName": "campaign_conversion",
          "properties": {
            "source": "{{campaign_source}}",
            "medium": "{{campaign_medium}}",
            "campaign": "{{campaign_name}}",
            "converted": true
          }
        }
      }
    },
    {
      "id": "analytics_not_converted",
      "type": "analytics",
      "position": { "x": 1300, "y": 150 },
      "data": {
        "label": "Não Converteu",
        "parameters": {
          "eventName": "campaign_no_conversion",
          "properties": {
            "source": "{{campaign_source}}",
            "medium": "{{campaign_medium}}",
            "campaign": "{{campaign_name}}",
            "converted": false
          }
        }
      }
    },
    {
      "id": "message_sim",
      "type": "message",
      "position": { "x": 1500, "y": 50 },
      "data": {
        "label": "Converteu",
        "parameters": {
          "message": "🎉 Ótimo! Sua conversão foi rastreada!"
        }
      }
    },
    {
      "id": "message_nao",
      "type": "message",
      "position": { "x": 1500, "y": 150 },
      "data": {
        "label": "Não Converteu",
        "parameters": {
          "message": "Tudo bem! Estaremos aqui quando precisar."
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 1700, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "variable_1" },
    { "source": "variable_1", "target": "analytics_1" },
    { "source": "analytics_1", "target": "message_1" },
    { "source": "message_1", "target": "input_1" },
    { "source": "input_1", "target": "condition_1" },
    { "source": "condition_1", "target": "analytics_converted", "label": "true" },
    { "source": "condition_1", "target": "analytics_not_converted", "label": "false" },
    { "source": "analytics_converted", "target": "message_sim" },
    { "source": "analytics_not_converted", "target": "message_nao" },
    { "source": "message_sim", "target": "end_1" },
    { "source": "message_nao", "target": "end_1" }
  ]
}

Saída esperada (conversão):

Sistema: 🔥 BLACK FRIDAY!

50% OFF em todos os produtos!

Quer aproveitar?
Sistema: Digite SIM para aproveitar:
Usuário: SIM
Sistema: 🎉 Ótimo! Sua conversão foi rastreada!

Resposta do Node

Google Analytics:

{
  "success": true,
  "action": "google_analytics_event_sent",
  "provider": "google_analytics",
  "eventName": "purchase_completed",
  "properties": {
    "value": 150.50,
    "currency": "BRL"
  },
  "timestamp": "2025-01-15T10:30:00.000Z"
}

Mixpanel:

{
  "success": true,
  "action": "mixpanel_event_sent",
  "provider": "mixpanel",
  "eventName": "Product Viewed",
  "properties": {
    "product": "iPhone 15",
    "source": "whatsapp"
  },
  "timestamp": "2025-01-15T10:30:00.000Z"
}

Sistema Padrão:

{
  "success": true,
  "action": "analytics_event_tracked",
  "event": {
    "eventName": "signup_completed",
    "properties": {
      "step": 3,
      "funnel": "registration"
    },
    "userId": "user_123",
    "sessionId": "session_456",
    "timestamp": "2025-01-15T10:30:00.000Z"
  },
  "timestamp": "2025-01-15T10:30:00.000Z"
}

Configuração de Providers

Google Analytics (GA4)

Variáveis de ambiente necessárias: 

GA_MEASUREMENT_ID=G-XXXXXXXXXX
GA_API_SECRET=seu_api_secret

Mixpanel

Variáveis de ambiente necessárias: 

MIXPANEL_TOKEN=seu_token_mixpanel

Amplitude

Requer implementação customizada com API key.

Segment

Requer implementação customizada com Write Key.

Boas Práticas

✅ SIM: - Use nomes de eventos consistentes (snake_case) - Inclua propriedades relevantes para análise - Rastreie eventos de negócio importantes - Combine com CONDITION para rastrear conversões - Use userId para análise cross-session - Documente seus eventos em um schema

❌ NÃO: - Não rastreie dados sensíveis (senhas, cartões) - Não use nomes de eventos genéricos ("click", "action") - Não envie payloads muito grandes (> 100KB) - Não abuse de tracking (performance) - Não rastreie informações pessoais sem consentimento

Dicas

💡 Nomenclatura: Use padrão consistente como categoria_acao (ex: product_viewed, cart_abandoned)

💡 Funis: Rastreie cada etapa com step number para análise de drop-off

💡 Properties: Sempre inclua contexto (source, medium, campaign) para segmentação

💡 Testing: Use provider "custom" durante desenvolvimento para não poluir dados reais

💡 Multi-provider: Envie para múltiplos providers usando branches paralelas

💡 GDPR: Respeite consentimento do usuário antes de rastrear

Próximo Node

→ LOGGER - Sistema de logs estruturados → METRIC - Rastrear métricas e KPIs customizados → EVENT - Rastrear eventos de negócio → TRACKING - Rastreamento avançado de comportamento