# Script di tracciamento

> Invia eventi di workspace e personalizzati dal tuo sito web con lo script di tracciamento di Emailit e una chiave di tracciamento pubblica. Installalo, traccia gli eventi, identifica i visitatori e limita la chiave ai tuoi siti.

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.

**Pannello**

  1. **Apri la scheda Tracking.** Vai a **Email API → Events**, seleziona la scheda **Tracking**, poi **Create tracking key**.

  2. **Dai un nome alla chiave.** Compila il campo **Name** con un nome che dica dove viene usata, ad esempio `Online shop`.

  3. **Limitala ai tuoi siti.** In **Allowed origins**, inserisci i tuoi siti, uno per riga, ad esempio `https://shop.example.com` o `*.example.com`. Lascia il campo vuoto per accettare qualsiasi sito. Vedi [Siti consentiti](#allowed-sites).

  4. **Crea la chiave.** Seleziona **Create**. Ora la scheda **Tracking** mostra lo snippet con la tua chiave già inserita.

**API**

  Chiama [Crea una chiave di tracciamento](/it/docs/api-reference/tracking-keys/create/). Il campo `key` della risposta va nell’URL dello script.

```bash
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`:

```html
<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](/it/docs/forms/install/) 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

```javascript
// 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](/it/docs/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](/it/docs/commerce/connect-your-shop/#record-shop-activity).

## Identifica i visitatori

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

```javascript
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:

```javascript
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](/it/docs/automations/triggers/#custom-event). Invia dal tuo server, con l’[API degli eventi](/it/docs/events/send-events/), 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](/it/docs/commerce/connect-your-shop/#identify-visitors), e quegli eventi guidano le automazioni.

## Cosa invia lo script

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

| Campo | Contenuto |
| --- | --- |
| `anonymous_id` | Un ID casuale del visitatore (`anon_…`), conservato nel local storage del browser. |
| `email`, `contact_id` | Ciò che hai passato a `identify`, se l’hai fatto. |
| `context.page` | `url`, `path`, `title` e `referrer` della pagina. |
| `context.campaign` | I parametri UTM della pagina (`utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content`), come `source`, `medium`, `name`, `term` e `content`. |
| `context.locale`, `context.timezone` | La lingua e il fuso orario del browser. |

Emailit aggiunge `identity_verified` agli eventi che indicano un contatto (vedi [Identifica i visitatori](#identify-visitors)) 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:

| Voce | Corrisponde a |
| --- | --- |
| `https://shop.example.com` | Esattamente quell’origine: schema, host e porta. |
| `shop.example.com` | Quell’host con qualsiasi schema o porta. |
| `*.example.com` | `example.com` e ogni sottodominio. |

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](/it/docs/events/send-events/).

## 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](/it/docs/events/#limits) previsto dal piano. Usa il [debug](#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

| Risposta nella console | Causa | Soluzione |
| --- | --- | --- |
| `403` `Origin not allowed for this tracking key` | Il sito della pagina non è in **Allowed origins**. | Aggiungilo, ad esempio sia `https://example.com` sia `https://www.example.com`, oppure usa `*.example.com`. |
| `403` `This tracking key is disabled` | La chiave è disattivata. | Attivala nella scheda **Tracking**. |
| `403` `Website tracking is included with Pro and Business.` | Il workspace è su Pay as you go. | Passa a Pro o Business. |
| `404` `Unknown tracking key` | La chiave nell’URL dello script è stata eliminata o digitata male. | Copia di nuovo lo snippet dalla scheda **Tracking**. |
| `422` con ogni evento in `rejected` | Nessuno degli eventi era valido. | Controlla i motivi in `rejected`. |
| `429` | La chiave ha inviato troppi eventi in poco tempo. | Invia meno eventi per visitatore, ad esempio nessun evento a ogni scorrimento o movimento del mouse. |
| Niente del tutto | Un blocco della pubblicità o del tracciamento ha fermato lo script, oppure lo script non è nella pagina. | Prova in un browser senza blocchi e controlla che lo snippet ci sia. |

## Vedi anche

  - [Tracciamento degli eventi](/it/docs/events/): Ambiti, nomi e dove finiscono gli eventi.
  - [Eventi di workspace](/it/docs/events/workspace-events/): Definisci gli eventi e le loro proprietà.
  - [API delle chiavi di tracciamento](/it/docs/api-reference/tracking-keys/): Crea, aggiorna ed elimina le chiavi.
  - [Invia eventi dal tuo backend](/it/docs/events/send-events/): Per ordini e pagamenti.

---
Fonte: https://emailit.com/it/docs/events/tracking-script/