Pular para conteúdo

GOOGLE_ANALYTICS - Rastreamento GA4

O que é este Node?

O GOOGLE_ANALYTICS é o node responsável por enviar eventos de rastreamento para o Google Analytics 4 (GA4) através da Measurement Protocol API, permitindo tracking de comportamento de usuários e conversões.

Por que este Node existe?

Integrar analytics manualmente requer conhecimento técnico da API do Google. O GOOGLE_ANALYTICS existe para:

  1. Rastreamento automático: Envia eventos para GA4 sem código customizado
  2. Análise de comportamento: Permite entender como usuários interagem com seus flows
  3. Métricas de conversão: Rastreia funis, conversões e objetivos
  4. Integração nativa: Funciona direto com Google Analytics 4 Measurement Protocol

Como funciona internamente?

Quando o GOOGLE_ANALYTICS é executado, o sistema:

  1. Valida configuração: Verifica se GA_MEASUREMENT_ID e GA_API_SECRET estão definidos
  2. Prepara payload: Cria estrutura de evento com client_id, nome e propriedades
  3. Envia para GA4: Faz POST para https://www.google-analytics.com/mp/collect
  4. Processa resposta: Google Analytics aceita evento assincronamente
  5. Se erro de config: Retorna erro de configuração ausente
  6. Se sucesso: Confirma envio do evento

Código interno (analytics-executor.service.ts:239-281): 

private async executeGoogleAnalytics(operation: string, eventName: string, properties: any, userId: string, context: any): Promise<any> {
  const measurementId = process.env.GA_MEASUREMENT_ID;
  const apiSecret = process.env.GA_API_SECRET;

  if (!measurementId || !apiSecret) {
    throw new Error('Google Analytics configuration missing');
  }

  const payload = {
    client_id: userId || this.generateClientId(),
    events: [{
      name: eventName,
      parameters: {
        ...properties,
        session_id: context.sessionId,
        engagement_time_msec: 100
      }
    }]
  };

  try {
    const url = `https://www.google-analytics.com/mp/collect?measurement_id=${measurementId}&api_secret=${apiSecret}`;

    await firstValueFrom(
      this.httpService.post(url, payload, {
        headers: {
          'Content-Type': 'application/json'
        }
      })
    );

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

Quando você DEVE usar este Node?

Use GOOGLE_ANALYTICS sempre que precisar de tracking com Google Analytics 4:

Casos de uso

  1. Rastrear conversões: "Usuário completou compra no WhatsApp"
  2. Análise de funil: "Usuário chegou no passo 3 do cadastro"
  3. Eventos customizados: "Botão clicado", "Formulário enviado"
  4. E-commerce tracking: "Produto adicionado ao carrinho"
  5. Engajamento: "Tempo de sessão", "Páginas visitadas"

Quando NÃO usar GOOGLE_ANALYTICS

  • Mixpanel é melhor: Use MIXPANEL para análise de produto detalhada
  • Segment como hub: Use SEGMENT para enviar para múltiplas plataformas
  • Analytics simples: Use CUSTOM_EVENT para tracking interno

Parâmetros Detalhados

provider (string, obrigatório)

O que é: Define o provedor de analytics. Para Google Analytics, use "google_analytics".

Padrão: N/A (obrigatório)

Flow completo para testar:

{
  "name": "Teste Google Analytics - 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 Evento GA4",
        "parameters": {
          "provider": "google_analytics",
          "eventName": "flow_started",
          "properties": {
            "flow_name": "Onboarding",
            "flow_version": "1.0"
          }
        }
      }
    },
    {
      "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: Execute o flow. Verifique no Google Analytics (Relatórios > Eventos em tempo real) se o evento flow_started aparece.

eventName (string, obrigatório)

O que é: Nome do evento a ser rastreado no Google Analytics.

Flow completo para testar:

{
  "name": "Teste Google Analytics - 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 Conversão",
        "parameters": {
          "provider": "google_analytics",
          "eventName": "purchase",
          "properties": {
            "currency": "BRL",
            "value": 99.90,
            "items": [
              {
                "item_id": "SKU123",
                "item_name": "Produto Teste",
                "price": 99.90,
                "quantity": 1
              }
            ]
          }
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Confirmar",
        "parameters": {
          "message": "💰 Compra rastreada no 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: Execute o flow. Confira em Google Analytics > Monetização se a compra foi registrada.

properties (object, opcional)

O que é: Propriedades customizadas do evento (dimensões e métricas).

Flow completo para testar:

{
  "name": "Teste Google Analytics - 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 com Propriedades",
        "parameters": {
          "provider": "google_analytics",
          "eventName": "button_click",
          "properties": {
            "button_name": "subscribe",
            "button_location": "header",
            "button_color": "blue",
            "user_segment": "premium",
            "campaign_id": "summer_2025"
          }
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Confirmar",
        "parameters": {
          "message": "Clique rastreado com 5 propriedades customizadas!"
        }
      }
    },
    {
      "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 no GA4 se as propriedades customizadas aparecem como parâmetros do evento.

userId (string, opcional)

O que é: Identificador único do usuário para vincular eventos ao mesmo perfil.

Flow completo para testar:

{
  "name": "Teste Google Analytics - 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 com User ID",
        "parameters": {
          "provider": "google_analytics",
          "eventName": "user_login",
          "userId": "{{user_email}}",
          "properties": {
            "login_method": "whatsapp"
          }
        }
      }
    },
    {
      "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 um email. O evento será vinculado ao client_id baseado nesse email.

Parâmetros

Campo Tipo Obrigatório Descrição
provider string Sim Deve ser "google_analytics"
eventName string Sim Nome do evento (ex: "purchase", "sign_up")
properties object Não Propriedades customizadas do evento
userId string Não Identificador único do usuário
operation string Não Tipo de operação (padrão: "track")

Configuração Necessária

Variáveis de Ambiente

Adicione no arquivo .env:

GA_MEASUREMENT_ID=G-XXXXXXXXXX
GA_API_SECRET=seu_api_secret_aqui

Como obter as credenciais:

  1. Measurement ID:
  2. Acesse Google Analytics
  3. Admin > Data Streams > Selecione seu stream

  4. Copie o "Measurement ID" (formato: G-XXXXXXXXXX)

  5. API Secret:

  6. Mesma tela do Measurement ID
  7. Role até "Measurement Protocol API secrets"
  8. Clique em "Create" e copie o secret gerado

Exemplo 1: Rastrear Funil de Conversão

Objetivo: Rastrear cada etapa de um funil de vendas no Google Analytics.

JSON para Importar

{
  "name": "Google Analytics - Funil de Vendas",
  "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: Visualização",
        "parameters": {
          "provider": "google_analytics",
          "eventName": "view_item",
          "properties": {
            "item_id": "PROD123",
            "item_name": "Curso TypeScript",
            "price": 297.00,
            "currency": "BRL"
          }
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Oferta",
        "parameters": {
          "message": "🎓 Curso TypeScript - R$ 297\n\nDeseja comprar?"
        }
      }
    },
    {
      "id": "input_2",
      "type": "input",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Capturar Resposta",
        "parameters": {
          "message": "Digite SIM para comprar",
          "variable": "resposta"
        }
      }
    },
    {
      "id": "analytics_2",
      "type": "analytics",
      "position": { "x": 900, "y": 100 },
      "data": {
        "label": "Etapa 2: Add to Cart",
        "parameters": {
          "provider": "google_analytics",
          "eventName": "add_to_cart",
          "properties": {
            "item_id": "PROD123",
            "item_name": "Curso TypeScript",
            "price": 297.00,
            "currency": "BRL",
            "quantity": 1
          }
        }
      }
    },
    {
      "id": "analytics_3",
      "type": "analytics",
      "position": { "x": 1100, "y": 100 },
      "data": {
        "label": "Etapa 3: Purchase",
        "parameters": {
          "provider": "google_analytics",
          "eventName": "purchase",
          "properties": {
            "transaction_id": "TXN_{{$timestamp}}",
            "value": 297.00,
            "currency": "BRL",
            "items": [
              {
                "item_id": "PROD123",
                "item_name": "Curso TypeScript",
                "price": 297.00,
                "quantity": 1
              }
            ]
          }
        }
      }
    },
    {
      "id": "message_2",
      "type": "message",
      "position": { "x": 1300, "y": 100 },
      "data": {
        "label": "Confirmação",
        "parameters": {
          "message": "✅ Compra confirmada!\n\n📊 Todo o funil foi rastreado no Google Analytics."
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 1500, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "analytics_1" },
    { "source": "analytics_1", "target": "message_1" },
    { "source": "message_1", "target": "input_2" },
    { "source": "input_2", "target": "analytics_2" },
    { "source": "analytics_2", "target": "analytics_3" },
    { "source": "analytics_3", "target": "message_2" },
    { "source": "message_2", "target": "end_1" }
  ]
}

Saída esperada:

Sistema: 🎓 Curso TypeScript - R$ 297. Deseja comprar?
Usuário: SIM
Sistema: ✅ Compra confirmada! Todo o funil foi rastreado no Google Analytics.

Exemplo 2: Rastrear Engajamento de Conteúdo

Objetivo: Monitorar quanto tempo usuários passam em diferentes seções do flow.

JSON para Importar

{
  "name": "Google Analytics - Engajamento",
  "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": "Página Inicial",
        "parameters": {
          "provider": "google_analytics",
          "eventName": "page_view",
          "properties": {
            "page_title": "Home",
            "page_location": "/home",
            "engagement_time_msec": 5000
          }
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Conteúdo",
        "parameters": {
          "message": "📚 Bem-vindo ao nosso curso!\n\nEscolha:\n1. Módulo 1\n2. Módulo 2"
        }
      }
    },
    {
      "id": "input_1",
      "type": "input",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Escolha",
        "parameters": {
          "message": "Digite 1 ou 2",
          "variable": "modulo"
        }
      }
    },
    {
      "id": "analytics_2",
      "type": "analytics",
      "position": { "x": 900, "y": 100 },
      "data": {
        "label": "Rastrear Escolha",
        "parameters": {
          "provider": "google_analytics",
          "eventName": "select_content",
          "properties": {
            "content_type": "module",
            "content_id": "module_{{modulo}}",
            "engagement_time_msec": 3000
          }
        }
      }
    },
    {
      "id": "message_2",
      "type": "message",
      "position": { "x": 1100, "y": 100 },
      "data": {
        "label": "Confirmar",
        "parameters": {
          "message": "✅ Módulo {{modulo}} selecionado!\n\n📊 Escolha rastreada no GA4."
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 1300, "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": "message_2" },
    { "source": "message_2", "target": "end_1" }
  ]
}

Saída esperada:

Sistema: 📚 Bem-vindo ao nosso curso! Escolha: 1. Módulo 1  2. Módulo 2
Usuário: 1
Sistema: ✅ Módulo 1 selecionado! Escolha rastreada no GA4.

Resposta do Node

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

Eventos Recomendados GA4

E-commerce

  • view_item - Visualização de produto
  • add_to_cart - Adicionar ao carrinho
  • begin_checkout - Iniciar checkout
  • purchase - Compra concluída
  • refund - Reembolso

Engajamento

  • page_view - Visualização de página
  • select_content - Seleção de conteúdo
  • share - Compartilhamento
  • video_start - Início de vídeo
  • video_complete - Vídeo completo

Conversões

  • sign_up - Cadastro
  • login - Login
  • generate_lead - Lead gerado
  • subscribe - Assinatura

Boas Práticas

✅ SIM:

  • Use eventos padrão do GA4 quando possível
  • Inclua currency e value em eventos de e-commerce
  • Defina userId para rastrear jornada completa
  • Teste eventos em tempo real antes de produção
  • Use propriedades descritivas e consistentes

❌ NÃO:

  • Não envie dados sensíveis (senhas, CPF, cartões)
  • Não use nomes de eventos genéricos ("click", "event")
  • Não esqueça de configurar GA_MEASUREMENT_ID e GA_API_SECRET
  • Não envie mais de 25 eventos por requisição

Dicas

💡 Dica 1: Use Google Analytics Debugger para validar eventos em tempo real (Relatórios > Tempo Real > Visão geral de eventos)

💡 Dica 2: Configure conversões em Admin > Eventos > Marcar como conversão para eventos importantes

💡 Dica 3: Use client_id consistente para vincular eventos da mesma sessão/usuário

💡 Dica 4: Combine com Google Tag Manager para criar triggers e variáveis avançadas

💡 Dica 5: Monitore limites da API (500 eventos por segundo por property)

Próximo Node

→ MIXPANEL - Event tracking com análise de produto → SEGMENT - Hub de analytics multi-plataforma → AMPLITUDE - Product analytics avançado