Schema degli eventi
Lo schema degli eventi descrive quali eventi devono arrivare al progetto e con quali proprietà: order_completed con un importo numerico obbligatorio, currency solo EUR o USD. OneTrace.pro confronta ogni evento con lo schema e mostra le violazioni: un errore di battitura nel nome dell'evento, un importo inviato come stringa, una proprietà mancante. Gli errori di tracciamento del sito o di un'integrazione emergono subito, e non quando un segmento o un report sono già stati calcolati in modo errato.
Un evento che viola lo schema viene comunque accettato e arriva nel profilo: i dati non vanno persi, anche se l'errore è nello schema stesso. Lo schema degli eventi è disponibile dal piano «Crescita».
Come descrivere gli eventi
Apra il Catalogo dati e la scheda Schema degli eventi. Lo schema può essere modificato dai ruoli con il permesso «Gestire il catalogo degli eventi», cioè dal «Manager» in su; gli altri vedono lo schema e le violazioni.
- Prema Aggiungi eventi attuali: nello schema entreranno tutti gli eventi del catalogo con le loro proprietà e i tipi rilevati. Oppure aggiunga gli eventi uno alla volta con il pulsante Aggiungi evento.
- Verifichi le proprietà di ogni evento:
| Colonna | Cosa imposta |
|---|---|
| Proprietà | La chiave della proprietà così come la invia il sito o il server, ad esempio amount |
| Tipo | Testo, numero, sì/no, data e ora, elenco o oggetto. Un valore di data e ora va bene anche per una proprietà di testo |
| Obbligatoria | Un evento senza questa proprietà o con un valore vuoto è una violazione |
| Valori consentiti | Separati da virgola, solo per testo e numeri. Un valore fuori elenco è una violazione; maiuscole e minuscole contano: eur ed EUR sono valori diversi |
| Descrizione | Per gli sviluppatori: che cosa significa la proprietà |
- Rimuova gli eventi e le proprietà che non devono più arrivare: se arrivano, sarà una violazione «Evento non descritto» o «Proprietà non descritta».
- Prema Salva schema e attivi Verifica gli eventi rispetto allo schema.
Le modifiche si accumulano sullo schermo e vengono salvate tutte insieme. Dopo il salvataggio i contatori delle violazioni ripartono da zero: quelli precedenti si riferiscono al vecchio schema. Nella scheda Eventi un evento dello schema che non è mai arrivato è contrassegnato come «Non ancora ricevuto», e gli eventi dello schema hanno l'indicazione «Nello schema».

Gli eventi di sistema della piattaforma ($identify, $page, $message_sent e altri), così come identify e le visualizzazioni di pagine e schermate dell'app, non vengono verificati: il loro schema è definito dalla piattaforma.
Violazioni
| Violazione | Esempio |
|---|---|
| Evento non descritto | È arrivato product_viewd invece di product_viewed |
| Proprietà non descritta | order_completed è arrivato con la proprietà coupon, che non è nello schema |
| Manca una proprietà obbligatoria | add_to_cart senza quantity |
| Tipo errato | L'importo è arrivato come stringa "1250" invece che come numero 1250 |
| Valore non consentito | currency = eur, mentre lo schema prevede EUR e USD |
Le violazioni degli ultimi 7 giorni sono visibili sopra l'elenco degli eventi dello schema: quante volte e quando è stata l'ultima, con un esempio, cioè il tipo del valore o il valore non consentito stesso. Senza il permesso di vedere i dati personali, l'esempio viene mascherato. Se un evento non è descritto per un errore dello schema e non del tracciamento, prema Aggiungi allo schema: verrà aggiunto alla bozza con le proprietà del catalogo.
Le stesse violazioni e il grafico degli eventi con violazioni nelle 24 ore si trovano nella sezione Diagnostica.

Importazione, esportazione e API
Esporta JSON scarica lo schema salvato, Importa JSON carica un file nella bozza: lo controlli e lo salvi. Così lo stesso schema si trasferisce da un progetto all'altro: ad esempio su tutti i negozi di una catena o da un progetto di test a quello di produzione.
Tramite l'API pubblica lo schema si legge (GET /api/v1/event-schema) e si sostituisce per intero (PUT /api/v1/event-schema, permesso della chiave «Modifica dello schema degli eventi»), mentre le violazioni dell'ultima settimana si ottengono con la richiesta GET /api/v1/event-schema/violations. Il formato del file e dell'API è lo stesso:
{
"enabled": true,
"events": [
{
"name": "order_completed",
"label": "Ordine completato",
"properties": [
{ "key": "amount", "type": "number", "required": true },
{ "key": "currency", "type": "string", "required": true, "values": ["EUR", "USD"] }
]
}
]
}
Gli eventi assenti dal documento escono dallo schema, ma restano nel catalogo dati con le loro etichette e statistiche. Un documento senza events attiva o disattiva soltanto la verifica.