DocsJavaScript API

JavaScript API: open de Nodale-agent vanuit je code

De nodale()-commando’s voor je pagina: open de agent vanuit je eigen knop of formulier, geef e-mailadres en context mee, meld de toestemming van de bezoeker.

Zodra de tag is geïnstalleerd, kan je pagina er commando’s naartoe sturen via één functie, nodale(). Er zijn twee commando’s: open en consent. De tag biedt geen andere methode en stuurt geen event naar je pagina.

De commandowachtrij

De tag definieert window.nodale wanneer hij draait. Wil je een commando aanroepen voordat de tag geladen is, plak dan deze stub erboven. Commando’s wachten in een wachtrij totdat de tag klaar is:

<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>

Laat de || staan. Een script dat later window.nodale toewijst zonder ||, verwijdert het commando van de tag, en latere aanroepen komen nergens aan.

nodale('open')

Opent de agent vanuit je eigen code, bijvoorbeeld vanuit je eigen knop of zodra je eigen formulier is verzonden.

nodale('open')

nodale('open', {
  email: 'sam@acme.io',
  context: { 'Contacten per maand': '1500' }
})

De aanroep start een geschreven gesprek in het dialoogvenster van de agent. De microfoon wordt niet aangevraagd: die wacht op de bezoeker.

Opties

Optie Type Wat het doet
email string Het e-mailadres van de bezoeker, als je pagina het al kent. De bezoeker wordt geïdentificeerd vóór de begroeting van de agent.
context object Wat de bezoeker je al heeft verteld, als paren van label en antwoord. De agent ontvangt het wanneer het gesprek start. Het wordt bij het gesprek vastgelegd en nooit aan de bezoeker getoond.

Beide zijn optioneel. De tag controleert het argument voordat er iets de pagina verlaat:

  • Het argument is niets, of een plain object zonder andere key dan email en context. Bij al het andere opent er niets.
  • email is een string van 1 tot 254 tekens na trimmen. Anders vervalt het, en de agent opent toch. De tag beoordeelt het adres niet: de server beslist of het wordt geaccepteerd.
  • context bevat maximaal 20 antwoorden. Een label telt 1 tot 60 tekens, een antwoord is een string van maximaal 300 tekens, en een label wordt één keer gebruikt. Labels en antwoorden worden getrimd, en een leeg antwoord wordt overgeslagen. Als één regel wordt geschonden, vervalt de hele context, nooit een deel ervan, en de agent opent toch, zonder context.

nodale('open') gooit nooit een fout en geeft undefined terug.

Waar het werkt

  • Alleen op de balk en op de weergave hidden. Met de knopweergave, met een inline <div data-nodale-agent>, en op een pagina waar de agent niet wordt getoond (een paginaregel, of een aandeel bezoekers), doet de aanroep niets. Gebruik je open, laat het aandeel bezoekers dan uit, anders doet de aanroep voor sommige bezoekers niets.
  • Voordat de tag geladen is, via de stub hierboven. Alleen de laatste open in de wachtrij wordt opnieuw afgespeeld, één keer.
  • Eén gesprek. De widget start maximaal één gesprek en bewaart het eerste e-mailadres en de eerste context die hij heeft ontvangen. Een open tijdens een gesprek, of nadat er een is afgelopen, toont alleen het dialoogvenster.
  • Als de agent eerst om het e-mailadres vraagt, toont de aanroep die stap, en je e-mailadres en context worden verstuurd wanneer de bezoeker die stap verzendt.

Vanuit een knop

<button type="button" onclick="nodale('open')">Stel een vraag</button>

Na je eigen formulier

form.addEventListener('submit', function () {
  nodale('open', {
    email: form.elements.email.value,
    context: {
      'Bedrijfsgrootte': form.elements.size.value,
      'Wat ze willen doen': form.elements.message.value
    }
  })
})

De weergave hidden

hidden is een weergave van de workspace, naast de balk en de knop. Hiermee is er niets te zien totdat je pagina nodale('open') aanroept.

  • De pagina blijft volledig bruikbaar. Het frame van de agent is gemount maar onzichtbaar, en het vangt geen enkele klik op.
  • Eenmaal geopend is het de balk. Het dialoogvenster sluiten brengt je terug naar de balk en bewaart het gesprek. De balk blijft daarna staan voor de rest van het tabblad.
  • Het tabblad onthoudt het. Een latere pagina van je site in hetzelfde tabblad toont de balk meteen, zodat de bezoeker het gesprek terugvindt. De tag bewaart dit in sessionStorage, in een key die geen identifier bevat. Een nieuw tabblad start verborgen.
  • Alleen getest in Chromium-browsers. Safari en Firefox vallen nog niet onder onze browsertests: een browser die onzichtbare frames vertraagt, kan later op open antwoorden.

nodale('consent')

Vertelt de tag of de bezoeker akkoord is gegaan met bezoektracking. Gebruik het wanneer je site geen cookiebanner heeft die de tag kan lezen, of wanneer je toestemming zelf beheert.

nodale('consent', 'granted')
nodale('consent', 'revoked')
  • Het telt alleen als bezoektracking aanstaat in je workspace. Tracking staat standaard uit, en de agent wordt in beide gevallen gemount.
  • Tracking start als geweigerd. Er wordt niets opgevraagd en er wordt geen cookie geschreven vóór een toestemming. Bij revoked stopt de tag en verwijdert hij zijn cookie.
  • Het gaat boven elke banner. Zodra je pagina het heeft aangeroepen, volgt de tag jouw aanroep en negeert hij wat een banner zegt.
  • Global Privacy Control wint van alles. Een browser die het meestuurt, blijft geweigerd voor het hele bezoek, wat je pagina ook aanroept.

Zonder de aanroep leest de tag het antwoord uit de toestemmingstool van de pagina: Axeptio, Didomi, Cookiebot, OneTrust, Usercentrics, CookieYes, tarteaucitron.js, WP Consent API, Complianz, de HubSpot-banner, iubenda, Osano, Cookie-Script, CookieFirst, Klaro, Shopify, Wix, IAB TCF v2.2, IAB GPP en Google Consent Mode v2. Bij sommige moet Nodale als vendor of als dienst worden aangemeld: de gids voor bezoektracking in de app geeft de setup voor elk ervan.

Debuggen

De tag gooit nooit een fout in je pagina. Hij legt zichzelf uit op console.debug, in regels die beginnen met nodale tag:. Zet het verbose-niveau van je browserconsole aan om ze te zien.

Regel Wat er gebeurde
open refused Het argument is geen plain object, of het bevat een andere key dan email en context.
open email dropped email is geen string van 1 tot 254 tekens.
open context dropped context schendt een van zijn regels.
open needs the floating or hidden display De workspace gebruikt de knopweergave, of de pagina mount de agent inline.
open: agent not on this page Een paginaregel of het aandeel bezoekers houdt de agent van deze pagina.
open not acknowledged De widget heeft niet binnen 30 seconden geantwoord.

Voor AI-agents: deze pagina in Markdown

Laat elk bezoek tellen.