O payload canônico de evento

O SupremeTracking aceita eventos de diferentes fontes, incluindo tags de navegador e webhooks. Cada fonte é traduzida para o mesmo Supreme Event Payload canônico antes de o Node processá-la.

Essa regra de canônico-primeiro mantém o código compartilhado do pipeline genérico. Tradutores de fonte tratam as diferenças de entrada, e cada integração de destino mapeia o evento canônico para o formato da própria plataforma.

Um evento canônico representativo

Os campos opcionais exatos dependem da fonte e do contexto disponível, mas um evento normalizado tem este formato:

{
  "event_id": "evt_example_123",
  "event_name": "purchase",
  "event_time": 1730000000,
  "channel": "webevents",
  "action_source": "browser",
  "provider": "direct",
  "property_id": 1,
  "source": "browser",
  "source_platform": "direct",
  "context": {
    "stuid": "0123456789abcdef0123456789abcdef",
    "session_id": "1.1730000000.0123456789abcdef",
    "page_url": "https://shop.example.com/thank-you",
    "page_title": "Order complete",
    "referrer": "https://shop.example.com/checkout",
    "utm": {},
    "tracking_ids": {}
  },
  "user": {
    "email": "buyer@example.com",
    "phone": null
  },
  "params": {
    "transaction_id": "order_123",
    "value": 99.9,
    "currency": "USD",
    "items": []
  }
}

Essa é a representação normalizada do Node, não um corpo de requisição bruto para copiar no endpoint de ingestão.

Campos principais

• event_id identifica o evento e viabiliza a deduplicação.
• event_name é a ação canônica, como page_view, lead, add_to_cart ou purchase.
• event_time é normalizado para segundos Unix.
• channel identifica a família de ingestão: web events, webhooks, eventos internos ou imports.
• action_source descreve onde a ação aconteceu, como browser ou server.
• provider identifica o provedor normalizado associado à fonte.
• property_id atribui o evento a uma Property ativa do Node. Não há fallback: um evento que não resolve para uma Property válida e ativa é rejeitado durante a validação.
• source e source_platform preservam contexto útil de origem.
• context carrega página, sessão, identidade de primeira parte, atribuição e contexto de requisição quando disponíveis.
• user contém campos normalizados do usuário. Capitalização de e-mail, formatação de telefone e aliases são normalizados pelo Node.
• params contém valores específicos do evento, como ID de transação, value, currency, status e items.

Não adicione lógica de destino específica de plataforma a esse formato compartilhado. Meta, GA4, Google Ads, CRM e outros handlers são donos do próprio mapeamento canônico-para-plataforma dentro dos seus módulos.

Os cinco estágios do pipeline

Depois da tradução, EventPipeline::process() roda estes estágios em ordem:

1. Filter aplica regras de rejeição antes de qualquer outro processamento.
2. Validation verifica se o evento canônico é aceitável.
3. Enrichment resolve e adiciona identidade e contexto disponíveis localmente.
4. Persistence armazena o evento resultante no Node.
5. Forwarding passa o evento canônico para cada handler de integração ativo.

Como Persistence roda antes de Forwarding, um evento pode estar visível no Console mesmo quando um destino depois o rejeita ou falha em recebê-lo. Use os logs do Node e o próprio diagnóstico do destino para investigar essa segunda metade.

Do GTM a um destino

O template atual do GTM monta um envelope de navegador e chama window.supremeSend. O Node traduz essa entrada para o formato canônico acima. Saiba como configurar a fonte em Connect Google Tag Manager (em inglês).

Os módulos de Forwarding então leem o evento canônico e montam os payloads de destino. Saiba como os módulos são separados em Visão geral de integrações.

Para inspecionar o resultado no seu próprio Node, verifique seu primeiro evento.