Integrazione con JavaScript Puro (Vanilla)

In questa sezione spiegheremo come puoi integrare il tuo sito web incorporando il script di Metricalp nel tuo sito web. Tutte le altre librerie di integrazione utilizzano questo metodo internamente.

Prima di tutto, hai bisogno del tuo tid (noto anche come Tracker ID). Puoi ottenerlo dalla schermata Impostazioni del Tracker / Incorpora & Condividi.

Dopo aver ottenuto il tuo tid, sei pronto per incorporare il script di Metricalp nel tuo sito web. Devi posizionare il seguente frammento di codice in cima a ogni pagina. Non dimenticare di sostituire YOUR_TID con il tuo tid.

<script src="https://cdn.metricalp.com/event/metricalp.js" data-allow-localhost="true" data-tid="YOUR_TID" defer></script>

Questo è tutto. Metricalp inizierà automaticamente a raccogliere eventi dal tuo sito web dopo questa singola riga. Fantastico, vero? 🫡

Ora andiamo nei dettagli. Il script sopra ha l'attributo `defer`, il che significa che il script non bloccherà il caricamento della pagina, ma l'esecuzione del script avverrà prima di qualsiasi altro script presente nella pagina che viene dopo questo script. Tuttavia, se vuoi caricare il script in modo asincrono, puoi rimuovere l'attributo `defer` e sostituirlo con l'attributo `async`. In questo caso, mentre il script verrà caricato in modo asincrono, potrebbe essere un problema se vuoi attivare un evento immediatamente dopo il caricamento della pagina, poiché potrebbe non essere completato il caricamento del script prima di attivare l'evento. Per risolvere questo problema e rendere il processo più fluido, possiamo aggiungere una riga in più appena sopra il nostro script:

<script>window.metricalp = window.metricalp || {queue: [], event: function(e){this.queue.push(e)}}</script>
<script src="https://cdn.metricalp.com/event/metricalp.js" data-allow-localhost="true" data-tid="YOUR_TID" async></script>

Ora abbiamo sostituito defer con async e abbiamo aggiunto una riga in più appena sopra la riga del nostro script. Garantiamo che ogni evento verrà accodato indipendentemente dal tempo di caricamento del nostro script principale. Poiché ora stiamo raccogliendo i nostri eventi in una coda fino a quando il nostro script non viene caricato, e poi attiva tutti gli eventi nella coda. Quindi, puoi attivare eventi immediatamente dopo il caricamento di una pagina. In generale, raccomandiamo questo secondo frammento di codice (lo utilizziamo nelle nostre librerie di integrazione) perché è più performante, sicuro e leggero per il caricamento della pagina.

Durante la fornitura dell'attributo data-tid, abbiamo fornito un altro attributo di dati data-allow-localhost="true" perché di default Metricalp non raccoglie mai eventi da localhost (127.0.0.1) per risparmiare sulla tua quota di utilizzo. Tuttavia, se stai integrando per la prima volta, puoi consentire eventi localhost a scopo di test. Una volta completata l'integrazione, puoi rimuovere questo attributo prima di pubblicare il tuo sito web in produzione. Informazioni dettagliate possono essere trovate nella documentazione di permettere localhost & escludimi.

Esistono alcune opzioni in più per personalizzare i comportamenti del script di Metricalp, puoi trovare tutto nella riferimento API.

Di default, Metricalp inizia automaticamente a raccogliere eventi screen_view (può essere disabilitato con l'opzione data-disable-auto-route-catch, si prega di consultare il riferimento API per i dettagli). Tuttavia, se vuoi attivare manualmente un evento (screen_view o qualsiasi evento personalizzato), puoi usare la funzione window.metricalp.event o attributi dati personalizzati. Imparerai di più su questo nella sezione Eventi Personalizzati & Props. Se stai attivando eventi personalizzati, il tuo script dovrebbe essere caricato prima che attivi l'evento. Generalmente, questo è il caso in entrambi i frammenti di codice sopra. Ma, nel primo scenario, se attivi l'evento prima della chiamata del script con defer, potrebbe esserci un errore. Anche se questo è un caso limite molto raro, puoi utilizzare il secondo frammento di codice per essere sicuro al 100%.

Inoltre, a volte potresti voler collegare automaticamente alcune proprietà personalizzate ad alcuni (o tutti) gli eventi. Puoi configurarlo con il secondo approccio e definire queste proprietà automaticamente collegate nell'oggetto sharedCustomProps come:

<script>
      window.metricalp = window.metricalp || {
          queue: [],
          sharedCustomProps: {
            _global: { custom_prop1: "Test1" },
            screen_view: {
              logged_in: 'not_logged_in',
              custom_prop2: "Test2",
            }
          },
          event: function(e){this.queue.push(e)}
      }
</script>
<script src="https://cdn.metricalp.com/event/metricalp.js" data-allow-localhost="true" data-tid="YOUR_TID" async></script>

_global è una chiave speciale per collegare alcune proprietà a tutti gli eventi. Tieni presente che, se stai collegando una proprietà personalizzata tramite un alias, quell'alias dovrebbe essere definito per gli eventi di destinazione nelle Impostazioni del Tracker; altrimenti, verrà ignorato per quell'evento. Puoi sempre utilizzare la sintassi custom_prop1 per qualsiasi evento. Di nuovo, puoi ottenere informazioni più dettagliate su sharedCustomProps nella sezione Eventi Personalizzati & Props. Se stai utilizzando la libreria React per integrare Metricalp con React / NextJS, puoi consultare la documentazione di React e NextJS per imparare come puoi configurare sharedCustomProps nella tua app React / NextJS.