Google Tag Manager (GTM) è uno dei metodi consigliati per distribuire lo script di tracciamento di Positive User sul tuo sito web. Una volta che GTM ha caricato lo script, Positive User inizia a tracciare i visitatori, crea i profili dei contatti e ti consente di arricchire tali profili con i dati rilevanti per la tua attività.
Questa guida copre tre aspetti:
Installazione dello script di implementazione di base;
Identificazione dei contatti tramite un Contact ID;
Estensione della configurazione con dati aggiuntivi del contatto e callback.
Un workspace Positive User attivo.
Informazioni relative alla chiave del workspace e al sottodominio (dalla sezione "Impostazioni workspace" → "API & Integrazioni" → "Setup & Integrazioni").
Accesso al container GTM installato sul tuo sito web.
Strategia di gestione dei cookie/consenso già definita.
Se il tuo sito utilizza una Content Security Policy, assicurati che i domini di Positive User siano inseriti nella whitelist.
Lo script di implementazione definisce un oggetto di configurazione (window.civchat) e poi carica "widget.js". Aggiungerlo tramite GTM significa poterlo distribuire, aggiornare o mettere in pausa senza dover intervenire nuovamente sul codice del sito web.
Ottieni la chiave e il sottodominio del tuo workspace
Nel tuo workspace Positive User, vai su "Impostazioni workspace" → "API & Integrazioni" → "Setup & Integrazioni" per trovare la chiave del workspace e prendi nota del sottodominio del tuo workspace (es. yourapp.user.com).
Crea il tag Custom HTML in GTM
Accedi al tuo container GTM e vai su "Tag" → "Nuovo" → "Configurazione tag" → "Custom HTML" e incolla lo script qui sotto. Sostituisci YOUR_KEY con la chiave del workspace ottenuta al passo 1, e yourapp.user.com con il sottodominio del tuo workspace:
<script data-cfasync="false" type="text/javascript">
window.civchat = {
apiKey: 'YOUR_KEY'
};
</script>
<script data-cfasync="false" src="https://yourapp.user.com/widget.js"></script>
Imposta il trigger nel container GTM
Alla voce "Attivazione", scegli il trigger più adatto alla tua configurazione del consenso — di solito è un evento "cookie_consent_update" (o equivalente). In questo modo lo script si carica solo dopo che il visitatore ha accettato i cookie. Se non hai un livello di consenso, "Tutte le pagine" funziona come punto di partenza.
Salva, Anteprima, Pubblica
Assegna un nome al tag (ad esempio, "Positive User - Script di tracciamento"), clicca su "Salva", quindi avvia la modalità "Anteprima" di GTM per verificare che il tag venga attivato e che il widget si carichi. Una volta verificato, invia e pubblica il container GTM.
Suggerimento: per verificare se lo script è completamente caricato su una pagina, apri la console del browser ed esegui typeof UE === 'object' && typeof userengage === 'function'. Se restituisce true, Positive User è pronto.
Per impostazione predefinita, Positive User traccia i visitatori in modo anonimo tramite un cookie (__ca__chat). Per trasformare un visitatore anonimo in un contatto riconosciuto — e mantenere la sua cronologia coerente tra dispositivi e sessioni — passa un Contact ID attraverso il campo "user_id" (attributo) su "window.civchat".
Scegliere il Contact ID giusto
Il valore che utilizzi come Contact ID dipende da come la tua azienda identifica le persone. Non esiste una scelta unica corretta; deve essere un identificatore stabile e univoco che puoi passare in modo coerente su tutti i touchpoint. Le tre opzioni più utilizzate sono:
ID del database interno: l'opzione più stabile, poiché non cambia mai anche se il contatto aggiorna la propria email. Utilizzata negli esempi di questo articolo.
Email in minuscolo: semplice da implementare e leggibile nel workspace, ma legata all'indirizzo email attuale del contatto.
Hash SHA-256 dell'email in minuscolo: stessa unicità dell'email, ma nessun dato personale grezzo passa attraverso GTM o le variabili del browser.
Per saperne di più sugli ID, leggi il nostro articolo. [LINK]
Scegli una strategia e mantienila su tutto il tuo sito e in tutti gli ambienti. Cambiare in seguito il formato del Contact ID può causare profili contatto duplicati o un'interruzione della continuità del tracciamento.
Il Contact ID deve essere disponibile quando viene definito "window.civchat" — vale a dire prima che venga caricato "widget.js". L'approccio standard è leggerlo dal dataLayer che il tuo sito popola per i contatti loggati, quindi assegnarlo all'oggetto "civchat" in modo condizionale.
Trova il Contact ID nel tuo dataLayer
Sulla maggior parte delle piattaforme di e-commerce (Magento, Shopify, WooCommerce, PrestaShop, ecc.), il dataLayer è già popolato con le informazioni sul cliente loggato, inclusi un customer ID, l'email e i campi di base del profilo. Non è necessario scrivere JavaScript da zero; devi solo sapere quale chiave del dataLayer contiene il valore che vuoi utilizzare come Contact ID.
Per verificare cosa è disponibile:
Apri GTM e clicca su "Anteprima" in alto a destra.
Inserisci l'URL del tuo sito web e accedi come cliente di test nella finestra di anteprima.
Nel Tag Assistant di GTM, apri la scheda "Data Layer" su qualsiasi evento.
Cerca tra le voci un oggetto che contenga informazioni sul cliente o sull'utente. Nomi di chiavi comuni sono "visitorId", "user_id", "customerId" o simili.
Se il Contact ID non è nel tuo DataLayer: contatta il tuo sviluppatore o l'amministratore della piattaforma e chiedigli di inserire un identificatore cliente stabile nel dataLayer per gli utenti loggati. È una piccola modifica lato piattaforma ed è un requisito comune per qualsiasi strumento di tracciamento o personalizzazione integrato tramite GTM.
Crea o riutilizza una variabile dataLayer in GTM
In GTM, vai su "Variabili" e verifica se esiste già una variabile per il tuo customer ID: nei container configurati da un'agenzia o per un'integrazione analytics esistente, spesso è già presente. Cerca variabili di tipo "Variabile del Data Layer" che puntano a chiavi come "customer_id" o "user_id". Se ne esiste già una, puoi riutilizzarla e passare direttamente allo step successivo.
Se non esiste ancora, vai su "Variabili" → "Nuova" → "Variabile del Data Layer" e creane una. Nel campo "Nome della variabile del Data Layer", inserisci il nome esatto della chiave che hai trovato nel tuo dataLayer (ad esempio, "customer_id"). Assegna alla variabile un nome riconoscibile, come "DLV - user_id".
Aggiorna il tag
Modifica il tag Custom HTML e assegna il Contact ID in modo condizionale, così che venga aggiunto solo quando il visitatore è effettivamente loggato:
<script data-cfasync="false" type="text/javascript">
var civchatConfig = {
apiKey: 'YOUR_KEY'
};
if ({{DLV - user_id}}) {
civchatConfig.user_id = {{DLV - user_id}};
}
window.civchat = civchatConfig;
</script>
<script data-cfasync="false" src="https://yourapp.user.com/widget.js"></script>
Quando "user_id" è presente, Positive User lo utilizza come identificatore principale. Se l'ID esiste già nel tuo workspace, il tracciamento passa al profilo di quel contatto; in caso contrario, l'ID viene assegnato alla sessione anonima corrente e viene creato un nuovo contatto.
Una volta identificato un contatto, puoi arricchirne il profilo con ulteriori campi — i campi dati memorizzati nel profilo del contatto. Passa questi valori al livello radice dell'oggetto di configurazione civchat, insieme a "user_id":
<script data-cfasync="false" type="text/javascript">
var civchatConfig = {
apiKey: 'YOUR_KEY'
};
if ({{DLV - user_id}}) {
civchatConfig.user_id = {{DLV - user_id}};
civchatConfig.email = {{DLV - user_email}};
civchatConfig.first_name = {{DLV - user_first_name}};
civchatConfig.last_name = {{DLV - user_last_name}};
civchatConfig.phone_number = {{DLV - user_phone}};
// Custom attributes go at the same level
civchatConfig.plan_type = {{DLV - user_plan}};
}
window.civchat = civchatConfig;
</script>
<script data-cfasync="false" src="https://yourapp.user.com/widget.js"></script>
Alcuni aspetti da tenere presente:
Campi standard vs. personalizzati: i campi standard (come "Email", "Numero di telefono", "Genere", "Stato") vengono riconosciuti automaticamente da Positive User. I campi personalizzati (come "Plan type") devono già esistere nel workspace: creali in anticipo. (Consulta "Come creare un campo personalizzato")
Il formato è importante: scegli sempre un tipo di campo adatto, poiché definisce le possibilità di filtro successive. Per l'elenco completo delle regole di formattazione, consulta la documentazione per sviluppatori o l'articolo "Cos'è un campo".
I valori sovrascrivono i dati esistenti: qualsiasi campo che passi in questo modo sostituirà il valore già memorizzato nel profilo del contatto. Passa i campi solo quando hai un valore reale: ecco perché li manteniamo all'interno del blocco "if" sopra.
I callback consentono al tuo codice di reagire a ciò che accade all'interno del widget Positive User — ad esempio, quando il widget termina il caricamento o quando arriva un nuovo messaggio in chat. Sono definiti come funzioni all'interno dello stesso oggetto di configurazione "civchat", insieme ad "apiKey" e "user_id".
Callback disponibili
L'SDK di Positive User espone i seguenti callback:
onLoad: viene eseguito una volta che lo script del widget e le sue risorse hanno terminato il caricamento. Utile per sequenziare altri tag GTM che dipendono dalla disponibilità di Positive User.
onMessage: viene eseguito ogni volta che viene ricevuto un messaggio in chat. L'oggetto "message" include un flag "isAdmin" che indica se il messaggio proviene da un membro del team/automazione (true) o dal contatto (false).
onOpen / onClose: viene eseguito quando il chat widget viene aperto o ridotto a icona.
onPayloadReceived: viene eseguito quando il widget riceve un payload dall'Automation module "Send Code".
Per il riferimento completo, consulta la documentazione per sviluppatori.
Lo script seguente mostra una configurazione completa che combina tutto ciò che è stato trattato in questa guida: il callback onLoad, il Contact ID, l'email e i dati aggiuntivi del contatto. Questa è la versione che puoi utilizzare come punto di partenza in produzione:
<script data-cfasync="false" type="text/javascript">
var civchatConfig = {
apiKey: 'YOUR_KEY',
// Notify GTM once the widget is fully loaded
onLoad: function() {
dataLayer.push({ event: 'Positive User - Widget Ready' });
}
};
// Identify the contact and pass their data only when logged in
if ({{DLV - user_id}}) {
civchatConfig.user_id = {{DLV - user_id}};
civchatConfig.email = {{DLV - user_email}};
civchatConfig.first_name = {{DLV - user_first_name}};
civchatConfig.last_name = {{DLV - user_last_name}};
civchatConfig.phone_number = {{DLV - user_phone}};
civchatConfig.plan_type = {{DLV - user_plan}};
}
window.civchat = civchatConfig;
</script>
<script data-cfasync="false" src="https://yourapp.user.com/widget.js"></script>
In GTM, puoi quindi creare un trigger di tipo "Evento personalizzato" in ascolto su "Positive User - Widget Ready" e utilizzarlo su qualsiasi tag che richieda la disponibilità dell'SDK di Positive User.
GTM è comodo, ma aggiunge un ulteriore livello tra il tuo sito web e Positive User. Se lo script non sembra attivarsi:
Controlla la modalità "Anteprima" di GTM per verificare che il tag venga effettivamente eseguito sulla pagina.
Assicurati che il container GTM sia pubblicato, non solo salvato.
Controlla la console del browser per eventuali errori JavaScript che potrebbero impedire l'esecuzione dello script.
Verifica che ad blocker, strumenti di gestione del consenso o il tuo CSP non stiano bloccando GTM o il dominio Positive User.
Verifica che le variabili del dataLayer si risolvano correttamente in modalità Anteprima: se una variabile è vuota, anche il campo corrispondente su "civchat" sarà vuoto.
Come configurare un chat widget [LINK]
Concetto di ID [LINK]