DocsJavaScript API
JavaScript API: den Nodale-Agenten aus Ihrem Code öffnen
Die nodale()-Befehle für Ihre Seite: den Agenten per eigenem Button oder Formular öffnen, E-Mail und Kontext übergeben, die Einwilligung des Besuchers melden.
Sobald das Tag installiert ist, kann Ihre Seite ihm über eine einzige Funktion Befehle senden: nodale(). Es gibt zwei Befehle: open und consent. Das Tag stellt keine andere Methode bereit und sendet kein Event an Ihre Seite.
Die Befehlswarteschlange
Das Tag definiert window.nodale, wenn es läuft. Um einen Befehl aufzurufen, bevor das Tag geladen ist, fügen Sie diesen Stub darüber ein. Die Befehle warten in einer Warteschlange, bis das Tag bereit ist:
<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>
Behalten Sie das || bei. Ein Script, das window.nodale später ohne es zuweist, entfernt den Befehl des Tags, und spätere Aufrufe laufen ins Leere.
nodale('open')
Öffnet den Agenten aus Ihrem eigenen Code, zum Beispiel über Ihren eigenen Button oder sobald Ihr eigenes Formular abgesendet ist.
nodale('open')
nodale('open', {
email: 'sam@acme.io',
context: { 'Kontakte pro Monat': '1500' }
})
Der Aufruf startet eine schriftliche Unterhaltung im Dialog des Agenten. Das Mikrofon wird nicht angefordert: Es wartet auf den Besucher.
Optionen
| Option | Typ | Was sie tut |
|---|---|---|
email |
string | Die E-Mail-Adresse des Besuchers, wenn Ihre Seite sie bereits kennt. Er wird vor der Begrüßung des Agenten identifiziert. |
context |
object | Was der Besucher Ihnen bereits mitgeteilt hat, als Paare aus Label und Antwort. Der Agent erhält es, wenn die Unterhaltung beginnt. Es wird an der Unterhaltung gespeichert und dem Besucher nie angezeigt. |
Beide sind optional. Das Tag prüft das Argument, bevor irgendetwas die Seite verlässt:
- Das Argument ist nichts oder ein einfaches Objekt ohne anderen Schlüssel als
emailundcontext. Bei allem anderen öffnet sich nichts. emailist ein String von 1 bis 254 Zeichen nach dem Trimmen. Andernfalls wird er verworfen, und der Agent öffnet sich trotzdem. Das Tag beurteilt die Adresse nicht: Der Server entscheidet, ob er sie annimmt.contextenthält höchstens 20 Antworten. Ein Label hat 1 bis 60 Zeichen, eine Antwort ist ein String von höchstens 300 Zeichen, und ein Label wird nur einmal verwendet. Labels und Antworten werden getrimmt, und eine leere Antwort wird übersprungen. Wird eine Regel verletzt, wird der gesamte Kontext verworfen, nie gekürzt, und der Agent öffnet sich trotzdem ohne ihn.
nodale('open') wirft nie eine Exception und gibt undefined zurück.
Wo es funktioniert
- Nur mit der Leiste und mit der Anzeige
hidden. Mit der Button-Anzeige, mit einem Inline-<div data-nodale-agent>und auf einer Seite, auf der der Agent nicht angezeigt wird (eine Seitenregel oder ein Anteil der Besucher), tut der Aufruf nichts. Wenn Sieopenverwenden, lassen Sie den Anteil der Besucher ausgeschaltet, sonst tut der Aufruf bei manchen Besuchern nichts. - Bevor das Tag geladen ist, über den Stub oben. Nur das letzte
openin der Warteschlange wird nachgeholt, einmal. - Eine Unterhaltung. Das Widget startet höchstens eine Unterhaltung und behält die erste E-Mail-Adresse und den ersten Kontext, die es erhalten hat. Ein
openwährend einer Unterhaltung oder nach deren Ende zeigt nur den Dialog. - Wenn der Agent zuerst nach der E-Mail-Adresse fragt, zeigt der Aufruf diesen Schritt, und Ihre E-Mail-Adresse und Ihr Kontext werden gesendet, wenn der Besucher ihn absendet.
Über einen Button
<button type="button" onclick="nodale('open')">Frage stellen</button>
Nach Ihrem eigenen Formular
form.addEventListener('submit', function () {
nodale('open', {
email: form.elements.email.value,
context: {
'Unternehmensgröße': form.elements.size.value,
'Was sie vorhaben': form.elements.message.value
}
})
})
Die versteckte Anzeige
hidden ist eine Anzeige des Workspace, neben der Leiste und dem Button. Mit ihr ist nichts zu sehen, bis Ihre Seite nodale('open') aufruft.
- Die Seite bleibt voll benutzbar. Der Frame des Agenten ist eingebunden, aber unsichtbar, und er fängt keinen Klick ab.
- Einmal geöffnet, ist es die Leiste. Das Schließen des Dialogs führt zur Leiste zurück und behält die Unterhaltung. Die Leiste bleibt dann für den Rest des Tabs.
- Der Tab merkt es sich. Eine spätere Seite Ihrer Website im selben Tab zeigt die Leiste sofort, sodass der Besucher die Unterhaltung wiederfindet. Das Tag speichert dies in
sessionStorage, in einem Schlüssel, der keine Kennung enthält. Ein neuer Tab startet versteckt. - Nur in Chromium-Browsern getestet. Safari und Firefox sind von unseren Browser-Tests noch nicht abgedeckt: Ein Browser, der unsichtbare Frames ausbremst, antwortet auf
openmöglicherweise später.
nodale('consent')
Teilt dem Tag mit, ob der Besucher dem Besuchs-Tracking zugestimmt hat. Verwenden Sie es, wenn Ihre Website kein Cookie-Banner hat, das das Tag lesen kann, oder wenn Sie die Einwilligung selbst verwalten.
nodale('consent', 'granted')
nodale('consent', 'revoked')
- Es zählt nur, wenn das Besuchs-Tracking in Ihrem Workspace eingeschaltet ist. Das Tracking ist standardmäßig aus, und der Agent wird in beiden Fällen eingebunden.
- Das Tracking startet als abgelehnt. Vor einer Zustimmung wird nichts angefordert und kein Cookie geschrieben. Bei
revokedstoppt das Tag und löscht sein Cookie. - Es hat Vorrang vor jedem Banner. Sobald Ihre Seite es aufgerufen hat, folgt das Tag Ihrem Aufruf und ignoriert, was ein Banner sagt.
- Global Privacy Control hat Vorrang vor allem. Ein Browser, der es sendet, bleibt für den gesamten Besuch abgelehnt, was auch immer Ihre Seite aufruft.
Ohne den Aufruf liest das Tag die Antwort aus dem Consent-Tool der Seite: Axeptio, Didomi, Cookiebot, OneTrust, Usercentrics, CookieYes, tarteaucitron.js, WP Consent API, Complianz, das HubSpot-Banner, iubenda, Osano, Cookie-Script, CookieFirst, Klaro, Shopify, Wix, IAB TCF v2.2, IAB GPP und Google Consent Mode v2. Bei einigen muss Nodale als Anbieter oder als Dienst deklariert sein: Die Anleitung zum Besuchs-Tracking in der App nennt die Einrichtung für jedes Tool.
Debugging
Das Tag wirft nie eine Exception in Ihre Seite. Es erklärt sich über console.debug, in Zeilen, die mit nodale tag: beginnen. Schalten Sie die Stufe Verbose Ihrer Browser-Konsole ein, um sie zu sehen.
| Zeile | Was passiert ist |
|---|---|
open refused |
Das Argument ist kein einfaches Objekt, oder es enthält einen anderen Schlüssel als email und context. |
open email dropped |
email ist kein String von 1 bis 254 Zeichen. |
open context dropped |
context verletzt eine seiner Regeln. |
open needs the floating or hidden display |
Der Workspace verwendet die Button-Anzeige, oder die Seite bindet den Agenten inline ein. |
open: agent not on this page |
Eine Seitenregel oder der Anteil der Besucher hält den Agenten von dieser Seite fern. |
open not acknowledged |
Das Widget hat nicht innerhalb von 30 Sekunden geantwortet. |