Pacotes

Dois entry points sobre uma única implementação.

Enviar uma segunda implementação de captura para o servidor significaria duas cópias do tratamento de cookies e leitura de consentimento divergindo com o tempo, o que aparece como dois comportamentos sob um mesmo nome e sem maneira de dizer, a partir de um dashboard, qual deles produziu uma linha. O entry point de servidor não captura nada: ele envia eventos que você já conhece, no mesmo formato de dados que o navegador usa, para o mesmo caminho de parsing no coletor.

Por que a metade de servidor existe

O navegador não consegue ver um webhook, um job em background ou um pagamento confirmado por um provedor três segundos depois que o cliente fechou a aba. Esses são os eventos de maior valor, porque carregam a receita que realmente foi liquidada em vez do total que estava no carrinho.

import { track } from '@vibiz/analytics/node';

await track({
  orgId: process.env.VIBIZ_ID,
  event: 'purchase',
  visitorId,                      // persisted with the order at checkout
  properties: { value: 49.9, currency: 'EUR', order_id: order.id },
});

Diga quem é o visitante, não quem é você

Uma chamada de servidor chega até nós a partir do seu datacenter. Lidas a partir da requisição, o endereço, o user agent e o país descrevem a sua infraestrutura em vez do seu cliente, e a Meta recebe um robô em Frankfurt como a pessoa que converteu. Envie os dados do próprio visitante, capturados na requisição que veio do navegador dele:

await track({
  orgId: process.env.VIBIZ_ID,
  event: 'purchase',
  visitorId,
  url: landingUrl,          // where the UTMs and the click id are read from
  clientIp, clientUserAgent, clientCountry,
  properties: { value: 49.9, currency: 'EUR', order_id: order.id },
});

url merece uma frase própria, porque nada a substitui. Nós não recebemos parâmetros UTM, nós os extraímos dessa string, junto com fbclid, gclid e ttclid. Um evento de servidor enviado sem ela não carrega nenhuma campanha e nenhum id de clique, ou seja, não é atribuível a nenhuma mídia paga. Envie a landing URL; conversões posteriores podem omiti-la, porque a aquisição já está registrada para o visitante.

Capture os três campos de cliente quando o navegador estiver à sua frente e mantenha-os com o pedido. Quando um webhook de pagamento dispara, a requisição nas suas mãos pertence à Stripe.

visitorId é o que vincula uma conversão do lado do servidor à visita que a produziu e, portanto, ao clique do anúncio. Ele pode ser lido a partir do cookie vbz_vid: armazenando-o com o pedido. Ele é a diferença entre uma compra atribuída a uma campanha e uma atribuída a ninguém.

Envie o mesmo order_id das duas metades. Sem isso, uma compra registrada em ambos os lugares é contada duas vezes, o que é pior do que não registrá-la em nenhum: os números parecem melhores e a otimização é treinada em receita que não existe.

Ela nunca lança exceção

track retorna um resultado em vez de disparar erro. Ele roda dentro de webhooks de pagamento e confirmações de pedido, e uma chamada de tracking que derruba um handler de checkout é um resultado muito pior do que um evento ausente.

Também não há tentativa de novo envio por baixo disso, de propósito. Um chamador dentro de um webhook já tem uma política de repetição imposta pelo provedor, e uma segunda por baixo dela produz eventos duplicados a cada nova entrega.

O protocolo de wire é apenas aditivo

Uma versão enviada hoje continuará postando o mesmo envelope em três anos. Campos podem ser adicionados, já que emissores antigos simplesmente os omitem, mas nunca renomeados, re-tipados ou receberem um novo significado. Mudar o formato exige uma nova versão e uma migração que substitui a antiga, nunca uma edição em produção.

É por isso que sid, d, el e pii são opcionais: cada um foi adicionado depois que o primeiro cliente foi enviado, e esse cliente ainda funciona.