DocsAPI JavaScript

API JavaScript: apri l’agente Nodale dal tuo codice

I comandi nodale() che una pagina può chiamare: apri l’agente da un tuo pulsante o form, passa email e contesto, segnala il consenso del visitatore.

Una volta installato il tag, la tua pagina può inviargli comandi tramite una sola funzione, nodale(). I comandi sono due: open e consent. Il tag non espone nessun altro metodo e non invia nessun evento alla tua pagina.

La coda dei comandi

Il tag definisce window.nodale quando viene eseguito. Per chiamare un comando prima che il tag sia caricato, incolla questo stub sopra di lui. I comandi aspettano in una coda finché il tag non è pronto:

<script>
  window.nodale = window.nodale || function(){(window.nodale.q = window.nodale.q || []).push(arguments)}
</script>
<script src="https://tag.nodale.app/v1/tag.js" data-workspace="YOUR_WORKSPACE_ID" async></script>

Mantieni il ||. Uno script che in seguito assegna window.nodale senza di esso rimuove il comando del tag, e le chiamate successive vanno a vuoto.

nodale('open')

Apre l’agente dal tuo codice, per esempio da un tuo pulsante o dopo l’invio di un tuo form.

nodale('open')

nodale('open', {
  email: 'sam@acme.io',
  context: { 'Contatti al mese': '1500' }
})

La chiamata avvia una conversazione scritta nella finestra di dialogo dell’agente. Il microfono non viene richiesto: aspetta il visitatore.

Opzioni

Opzione Tipo Cosa fa
email string L’email del visitatore, quando la tua pagina la conosce già. Il visitatore è identificato prima del saluto dell’agente.
context object Ciò che il visitatore ti ha già detto, in coppie etichetta e risposta. L’agente lo riceve all’avvio della conversazione. Viene registrato sulla conversazione e mai mostrato al visitatore.

Entrambe sono facoltative. Il tag controlla l’argomento prima che qualcosa lasci la pagina:

  • L’argomento è assente, oppure è un oggetto semplice senza chiavi diverse da email e context. In ogni altro caso non si apre nulla.
  • email è una stringa da 1 a 254 caratteri, tolti gli spazi iniziali e finali. Altrimenti viene scartata, e l’agente si apre comunque. Il tag non giudica l’indirizzo: è il server a decidere se accettarlo.
  • context contiene 20 risposte al massimo. Un’etichetta ha da 1 a 60 caratteri, una risposta è una stringa di 300 caratteri al massimo, e un’etichetta si usa una volta sola. A etichette e risposte vengono tolti gli spazi iniziali e finali, e una risposta vuota viene saltata. Se una regola è violata l’intero contesto viene scartato, mai tagliato, e l’agente si apre comunque senza.

nodale('open') non lancia mai eccezioni e restituisce undefined.

Dove funziona

  • Solo con la barra e con la visualizzazione hidden. Con la visualizzazione a pulsante, con un <div data-nodale-agent> inline, e in una pagina in cui l’agente non viene mostrato (una regola di pagina, o una quota di visitatori), la chiamata non fa nulla. Se usi open, tieni disattivata la quota di visitatori, altrimenti per alcuni visitatori la chiamata non fa nulla.
  • Prima che il tag sia caricato, tramite lo stub qui sopra. Solo l’ultimo open in coda viene rieseguito, una volta.
  • Una sola conversazione. Il widget avvia una conversazione al massimo e conserva la prima email e il primo contesto ricevuti. Un open durante una conversazione, o dopo che una è terminata, mostra soltanto la finestra di dialogo.
  • Quando l’agente chiede prima l’email, la chiamata mostra quel passaggio, e la tua email e il tuo contesto vengono inviati quando il visitatore lo conferma.

Da un pulsante

<button type="button" onclick="nodale('open')">Fai una domanda</button>

Dopo un tuo form

form.addEventListener('submit', function () {
  nodale('open', {
    email: form.elements.email.value,
    context: {
      'Dimensione aziendale': form.elements.size.value,
      'Cosa vuole fare': form.elements.message.value
    }
  })
})

La visualizzazione hidden

hidden è una visualizzazione del workspace, accanto alla barra e al pulsante. Con questa, non si vede nulla finché la tua pagina non chiama nodale('open').

  • La pagina resta del tutto utilizzabile. Il frame dell’agente è montato ma invisibile, e non intercetta nessun clic.
  • Una volta aperta, è la barra. Chiudere la finestra di dialogo riporta alla barra e conserva la conversazione. La barra resta poi per il resto della scheda del browser.
  • La scheda del browser se lo ricorda. Una pagina successiva del tuo sito nella stessa scheda mostra subito la barra, così il visitatore ritrova la conversazione. Il tag lo conserva in sessionStorage, in una chiave che non contiene nessun identificativo. Una nuova scheda parte nascosta.
  • Testata solo nei browser Chromium. Safari e Firefox non sono ancora coperti dai nostri test su browser: un browser che rallenta i frame invisibili può rispondere a open più tardi.

nodale('consent')

Dice al tag se il visitatore ha accettato il tracciamento delle visite. Usalo quando il tuo sito non ha un banner dei cookie che il tag sa leggere, o quando gestisci tu il consenso.

nodale('consent', 'granted')
nodale('consent', 'revoked')
  • Conta solo quando il tracciamento delle visite è attivo nel tuo workspace. Il tracciamento è disattivato per impostazione predefinita, e l’agente viene montato in entrambi i casi.
  • Il tracciamento parte negato. Nulla viene richiesto e nessun cookie viene scritto prima di un consenso. Con revoked, il tag si ferma ed elimina il suo cookie.
  • Prevale su ogni banner. Una volta che la tua pagina l’ha chiamato, il tag segue la tua chiamata e ignora ciò che dice un banner.
  • Global Privacy Control vince su tutto. Un browser che lo invia resta negato per tutta la visita, qualunque cosa chiami la tua pagina.

Senza la chiamata, il tag legge la risposta dallo strumento di consenso della pagina: Axeptio, Didomi, Cookiebot, OneTrust, Usercentrics, CookieYes, tarteaucitron.js, WP Consent API, Complianz, il banner di HubSpot, iubenda, Osano, Cookie-Script, CookieFirst, Klaro, Shopify, Wix, IAB TCF v2.2, IAB GPP e Google Consent Mode v2. Alcuni richiedono che Nodale sia dichiarato come fornitore o come servizio: la guida al tracciamento delle visite nell’app dà la configurazione per ciascuno.

Debug

Il tag non lancia mai eccezioni nella tua pagina. Si spiega su console.debug, in righe che iniziano con nodale tag:. Attiva il livello verbose della console del tuo browser per vederle.

Riga Cosa è successo
open refused L’argomento non è un oggetto semplice, oppure contiene una chiave diversa da email e context.
open email dropped email non è una stringa da 1 a 254 caratteri.
open context dropped context viola una delle sue regole.
open needs the floating or hidden display Il workspace usa la visualizzazione a pulsante, oppure la pagina monta l’agente inline.
open: agent not on this page Una regola di pagina o la quota di visitatori tiene l’agente fuori da questa pagina.
open not acknowledged Il widget non ha risposto entro 30 secondi.

Per gli agenti AI: questa pagina in Markdown