Script di tracciamento

Lo script di tracciamento invia eventi dal tuo sito web: visualizzazioni di prodotti, registrazioni, articoli aggiunti al carrello. Non richiede una chiamata di configurazione; la chiave di tracciamento fa parte del suo URL. Questa pagina spiega come creare una chiave, aggiungere lo script, tracciare gli eventi e collegarli ai tuoi visitatori.

Prima di iniziare

• Lo script di tracciamento è incluso nei piani Pro, Business e Custom. Con Pay as you go non puoi creare chiavi di tracciamento, e le richieste dello script restituiscono 403, anche con le chiavi create prima del passaggio a Pay as you go.
• Per creare chiavi di tracciamento nel pannello, ti serve il ruolo Admin nel workspace. Con l’API, usa una chiave con Full Access.
• Devi poter modificare l’HTML del sito, oppure aggiungere un tag HTML personalizzato nel tuo tag manager.

Crea una chiave di tracciamento

Le chiavi di tracciamento sono pubbliche: finiscono nelle tue pagine web, quindi chiunque può leggerle. Possono solo inviare eventi di workspace e personalizzati, mai leggere dati, e puoi limitarle ai tuoi siti.

curl -X POST https://api.emailit.com/v2/tracking-keys \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Online shop", "allowed_origins": ["https://shop.example.com"] }'

Aggiungi lo script

Incolla entrambi i tag in ogni pagina, preferibilmente prima di </head>, con la tua chiave al posto di TRACKING_KEY:

<script>window.emailit=window.emailit||function(){(window._emailitq=window._emailitq||[]).push(arguments)};</script>
<script async src="https://js.emailit.com/track/TRACKING_KEY/events.js"></script>

Il primo tag mette in coda le chiamate fatte prima che lo script si carichi, così puoi chiamare emailit(...) subito. Lo script si carica in modo asincrono, non genera mai eccezioni nella tua pagina e funziona anche da un tag manager.

• Se nella pagina c’è anche lo script dei moduli di Emailit, mantienili entrambi. Condividono window.emailit.
• Se il sito usa una Content Security Policy, consenti https://js.emailit.com in script-src e connect-src.

Traccia gli eventi

// Custom event: any name after "c:", any properties
emailit("track", "c:product.viewed", { sku: "TS-42", price: 19.9 });

// Workspace event: checked against its definition
emailit("track", "w:customer.type", { segment: "b2b" });

Il tipo deve iniziare con c: o w:; lo script ignora le altre chiamate. Le proprietà che non sono un oggetto vengono inviate come {}. Per gli eventi avvenuti in precedenza puoi passare un terzo argomento con occurred_at, una data e ora ISO 8601.

Lo script non registra da solo le visualizzazioni di pagina. Traccia le pagine e le azioni che ti interessano, ad esempio con un evento c:page.viewed a ogni cambio di route di una single-page app.

Comandi per i negozi

Per i negozi online, lo script ha anche i comandi product, cart, purchase e page. Registrano visualizzazioni di prodotto, carrelli e ordini per l’e-commerce e li inviano al log degli eventi come eventi di sistema product.viewed, cart.updated e order.placed. L’e-commerce è in alpha e aperto solo al team di Emailit; altrove questi comandi vengono rifiutati. Vedi Collega il tuo negozio.

Identifica i visitatori

Quando sai chi è il visitatore, ad esempio dopo l’accesso o l’iscrizione, comunicalo allo script:

emailit("identify", { email: "jane@example.com" });
// or, if you store Emailit contact IDs:
emailit("identify", { contact_id: "con_2wPq7Lm3XcN8bV1zKd4RtY6sHf9" });

Ogni evento successivo contiene quell’email o quell’ID contatto, in questa pagina e nelle visite successive, così Emailit può collegarlo al contatto. Quando il visitatore si disconnette, dimenticalo:

emailit("reset");

La chiamata reset genera anche un nuovo ID anonimo del visitatore, così la persona successiva su un computer condiviso non viene confusa con la precedente.

Gli eventi con un’email che nessun contatto ha vengono conservati, e compaiono sul contatto quando questo esiste. Un contact_id che non corrisponde a un contatto viene tolto dall’evento, senza errori, così una chiave pubblica non può servire a scoprire quali ID contatto esistono.

Chiunque abbia la tua chiave di tracciamento può chiamare identify con qualsiasi indirizzo, quindi Emailit non lascia che gli eventi dello script guidino le automazioni. Vengono registrati, compaiono sul contatto e arrivano ai webhook, ma non avviano, non terminano e non fanno avanzare le esecuzioni delle automazioni. Invia dal tuo server, con l’API degli eventi, gli eventi che devono farlo. Ogni evento dello script che indica un contatto ha identity_verified: è true solo quando un link firmato in una delle tue email ha identificato il visitatore, cosa che fa parte dell’alpha dell’e-commerce, e quegli eventi guidano le automazioni.

Cosa invia lo script

Oltre al tipo e alle proprietà, ogni evento contiene:

Emailit aggiunge identity_verified agli eventi che indicano un contatto (vedi Identifica i visitatori) e salva lo user agent del browser. Non salva gli indirizzi IP, e lo script non imposta cookie. Lo script conserva l’ID del visitatore in emailit:aid e l’identità in emailit:identity nel local storage; se il local storage è bloccato, durano solo quanto la pagina.

Gli eventi vengono raccolti per un attimo e inviati insieme, al massimo 20 alla volta. Quando il visitatore lascia la pagina, i rimanenti vengono inviati con sendBeacon.

Se sul tuo sito ti serve il consenso per gli strumenti di analisi, carica lo script solo dopo che il visitatore ha acconsentito.

Siti consentiti

Il campo allowed_origins limita i siti che possono inviare eventi con una chiave. Ogni voce è una delle seguenti:

Un elenco vuoto accetta qualsiasi sito. Emailit controlla l’header Origin che i browser inviano con ogni richiesta, quindi altri siti web non possono inviare eventi con la tua chiave. Uno script fuori da un browser, però, può impostare qualsiasi header: considera quindi gli eventi del browser come input non attendibile e invia ordini e pagamenti dal tuo backend.

Eventi non validi

A differenza dell’API, l’endpoint dello script salva gli eventi validi di una richiesta anche quando altri non sono validi. Gli eventi non validi vengono scartati, ad esempio un evento w: con una proprietà del tipo sbagliato, oppure un evento di un nuovo tipo quando il workspace usa il numero di tipi di evento previsto dal piano. Usa il debug per vederne il motivo.

Debug

Attiva i log nella console del browser in uno di questi modi:

• Chiama emailit("debug", true).
• Aggiungi data-debug al tag script.
• Apri la pagina con ?emailit_debug=1 nell’URL.

La console mostra quindi ogni evento e la risposta di Emailit, compresi i motivi degli eventi rifiutati.

Risoluzione dei problemi

Vedi anche