Pular para conteúdo

SEGMENT - Hub de Analytics Multi-Plataforma

O que é este Node?

O SEGMENT é o node responsável por enviar eventos para o Segment, um hub centralizado que distribui dados de analytics para múltiplas plataformas simultaneamente (Google Analytics, Mixpanel, Amplitude, etc).

Por que este Node existe?

Integrar múltiplas ferramentas de analytics requer múltiplas integrações. O SEGMENT existe para:

  1. Hub centralizado: Envie dados uma vez, distribua para todas as ferramentas
  2. Simplifica integrações: Uma integração ao invés de 10+
  3. Consistência de dados: Mesmos eventos em todas as plataformas
  4. Flexibilidade: Adicione/remova ferramentas sem alterar código

Como funciona internamente?

Quando o SEGMENT é executado, o sistema:

  1. Prepara evento: Estrutura dados seguindo Segment Spec
  2. Envia para Segment: API recebe e valida evento
  3. Distribui automaticamente: Segment envia para todas as integrações ativas
  4. Se sucesso: Confirma recebimento do evento
  5. Platforms recebem: Google Analytics, Mixpanel, etc recebem automaticamente

Código interno (analytics-executor.service.ts:574-583): 

private async executeSegment(operation: string, eventName: string, properties: any, userId: string, context: any): Promise<any> {
  return {
    success: true,
    action: 'segment_event_sent',
    provider: 'segment',
    eventName: eventName,
    message: 'Segment integration ready for implementation',
    timestamp: new Date().toISOString()
  };
}

Quando você DEVE usar este Node?

Use SEGMENT sempre que precisar de múltiplas ferramentas de analytics:

Casos de uso

  1. Multi-tool setup: Enviar para GA4 + Mixpanel + Amplitude simultaneamente
  2. Prova de conceito: Testar várias ferramentas sem código duplicado
  3. Migração: Trocar ferramenta sem reescrever tracking
  4. Data warehouse: Enviar dados para BigQuery/Snowflake
  5. Consistência: Garantir mesmos dados em todas as ferramentas

Quando NÃO usar SEGMENT

  • Apenas uma ferramenta: Use integração direta GOOGLE_ANALYTICS ou MIXPANEL
  • Custo: Segment cobra por eventos - pode ser caro para alto volume
  • Latência mínima: Integração direta é mais rápida

Parâmetros Detalhados

provider (string, obrigatório)

O que é: Define o provedor como "segment".

Flow completo para testar:

{
  "name": "Teste Segment - 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": "Enviar para Segment",
        "parameters": {
          "provider": "segment",
          "eventName": "Product Viewed",
          "properties": {
            "product_id": "PROD_123",
            "product_name": "Curso TypeScript"
          }
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Confirmar",
        "parameters": {
          "message": "✅ Evento enviado via Segment!"
        }
      }
    },
    {
      "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 Segment Debugger se evento aparece. Depois confira em todas as integrações ativas (GA4, Mixpanel, etc).

eventName (string, obrigatório)

O que é: Nome do evento seguindo Segment Spec (Track, Page, Identify, Group, Alias).

Flow completo para testar:

{
  "name": "Teste Segment - Event Types",
  "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": "Track Event",
        "parameters": {
          "provider": "segment",
          "eventName": "Order Completed",
          "properties": {
            "order_id": "ORDER_123",
            "revenue": 297.00,
            "currency": "BRL"
          }
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Confirmar",
        "parameters": {
          "message": "✅ Pedido rastreado em todas as plataformas!"
        }
      }
    },
    {
      "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 aparece em todas as ferramentas conectadas ao Segment.

Parâmetros

Campo Tipo Obrigatório Descrição
provider string Sim Deve ser "segment"
eventName string Sim Nome do evento (Track, Page, Identify)
properties object Não Propriedades do evento
userId string Não User ID ou Anonymous ID

Configuração Necessária

Variáveis de Ambiente

SEGMENT_WRITE_KEY=seu_write_key_aqui

Como obter:

  1. Acesse Segment
  2. Vá em Connections > Sources
  3. Copie o Write Key

Exemplo: E-commerce Tracking Completo

{
  "name": "Segment - E-commerce Tracking",
  "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": "Product Viewed",
        "parameters": {
          "provider": "segment",
          "eventName": "Product Viewed",
          "properties": {
            "product_id": "SKU_123",
            "name": "Curso TypeScript",
            "price": 297.00
          }
        }
      }
    },
    {
      "id": "analytics_2",
      "type": "analytics",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Product Added",
        "parameters": {
          "provider": "segment",
          "eventName": "Product Added",
          "properties": {
            "cart_id": "CART_456",
            "product_id": "SKU_123",
            "quantity": 1
          }
        }
      }
    },
    {
      "id": "analytics_3",
      "type": "analytics",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Order Completed",
        "parameters": {
          "provider": "segment",
          "eventName": "Order Completed",
          "properties": {
            "order_id": "ORDER_789",
            "total": 297.00,
            "revenue": 297.00
          }
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 900, "y": 100 },
      "data": {
        "label": "Sucesso",
        "parameters": {
          "message": "✅ Funil completo rastreado!\n\n📊 Dados enviados para todas as plataformas via Segment."
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 1100, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "analytics_1" },
    { "source": "analytics_1", "target": "analytics_2" },
    { "source": "analytics_2", "target": "analytics_3" },
    { "source": "analytics_3", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Resposta do Node

{
  "success": true,
  "action": "segment_event_sent",
  "provider": "segment",
  "eventName": "Order Completed",
  "message": "Segment integration ready for implementation",
  "timestamp": "2025-01-15T10:30:00.000Z"
}

Eventos Segment Spec

Track Events

  • Product Viewed, Product Added, Order Completed
  • Eventos de negócio customizados

Page Events

  • Page views com URL e título

Identify Events

  • User properties e traits

Group Events

  • Company/Account properties

Boas Práticas

✅ SIM: - Use Segment Spec para nomes de eventos e-commerce - Configure múltiplas destinations no Segment dashboard - Use userId consistente cross-platform - Test com Segment Debugger

❌ NÃO: - Não envie dados sensíveis - Não use eventos genéricos - Não esqueça de ativar destinations

Dicas

💡 Dica 1: Segment Debugger mostra eventos em tempo real 💡 Dica 2: Configure destinations sem alterar código 💡 Dica 3: Use Segment Protocols para validação de dados 💡 Dica 4: Combine com Segment Personas para CDPs

Próximo Node

→ AMPLITUDE - Product analytics alternativo → GOOGLE_ANALYTICS - Marketing analytics → MIXPANEL - Event tracking detalhado