Pacchetti

Due entry point su un’unica implementazione.

Consegnare una seconda implementazione di raccolta per il server significherebbe due copie della gestione dei cookie e della lettura del consenso che col tempo divergono, e questo si traduce in due comportamenti con lo stesso nome e nessun modo, da una dashboard, per capire quale dei due ha prodotto una riga. L’entry point server non raccoglie nulla: invia eventi che conosci già, usando lo stesso formato su wire del browser, nello stesso percorso di parsing sul collector.

Perché esiste la parte server

Il browser non può vedere un webhook, un job in background o un pagamento confermato da un provider tre secondi dopo che il cliente ha chiuso la scheda. Questi sono gli eventi che valgono di più, perché portano il fatturato realmente incassato invece del totale che era nel carrello.

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 },
});

Indica chi è il visitatore, non chi sei tu

Una chiamata server ci raggiunge dal tuo datacentre. Se leggiamo la richiesta, indirizzo, user agent e paese descrivono la tua infrastruttura e non il tuo cliente, e a Meta viene passato un robot a Francoforte come la persona che ha convertito. Invia invece i dati del visitatore, rilevati dalla richiesta proveniente dal suo browser:

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 merita una frase a sé, perché nulla può sostituirlo. Non riceviamo parametri UTM, li estraiamo da quella stringa, insieme a fbclid, gclid e ttclid. Un evento server inviato senza url non porta alcuna campagna e nessun click id, il che significa che non è attribuibile a nessuna attività pubblicitaria. Invia la landing URL; le conversioni successive possono ometterla, perché l’acquisizione è già registrata sul visitatore.

Rileva i tre campi client quando il browser è davanti a te e conservali con l’ordine. Quando un webhook di pagamento viene eseguito, la richiesta nelle tue mani appartiene a Stripe.

visitorId è ciò che collega una conversione lato server alla visita che l’ha prodotta, e quindi al click dell’annuncio. È leggibile dal cookie vbz_vid: salvalo insieme all’ordine. È la differenza tra un acquisto attribuito a una campagna e uno attribuito a nessuno.

Invia lo stesso order_id da entrambe le parti. Senza questo, un acquisto tracciato in entrambi i punti viene contato due volte, il che è peggio che non tracciarlo affatto: i numeri sembrano migliori e l’ottimizzazione viene addestrata su un fatturato che non esiste.

Non genera mai eccezioni

track restituisce un risultato invece di sollevare un’eccezione. Viene eseguito all’interno di webhook di pagamento e conferme d’ordine, e una chiamata di tracking che manda in errore un handler di checkout è un esito molto peggiore di un evento mancante.

Non c’è neppure alcun retry sotto al livello della funzione, di proposito. Un chiamante all’interno di un webhook ha già una politica di retry imposta dal provider, e una seconda politica al di sotto genera eventi duplicati a ogni nuovo tentativo di consegna.

Il wire protocol è solo append

Una versione distribuita oggi continuerà a inviare la stessa busta tra tre anni. I campi possono essere aggiunti, perché i sender più vecchi semplicemente li omettono, ma non verranno mai rinominati, cambiati di tipo o modificati nel significato. Cambiare la struttura richiede una nuova versione e una migrazione che solleva la vecchia, mai una modifica in-place.

Questo è il motivo per cui sid, d, el e pii sono opzionali: ognuno è stato aggiunto dopo la prima release del client, e quel client funziona ancora.