Conversations SDK
Mit dem Live-Chat-Widget von HubSpot können Sie mit Kunden und Leads auf Ihrer eigenen Website chatten. Mit dem Chat-Widget-SDK können Sie Besuchern ein individuelleres Erlebnis bieten, indem Sie das Verhalten des Chat-Widgets anpassen.
Anwendungsfall: Das Chat-Widget-SDK kann verwendet werden, um anzupassen, wann und wie das Chat-Widget von HubSpot auf Ihrer Website angezeigt wird.
Auf allgemeiner Ebene können Sie Folgendes tun:
- Das Verhalten des Widgets steuern
- Auf Events im Widget überwachen und darauf reagieren
- Abfragen, um den Widget-Zustand nachzuvollziehen
Erste Schritte
Die API befindet sich im window.HubSpotConversations
-Objekt. Alle verfügbaren Methoden können über dieses Objekt aufgerufen werden. Der HubSpot-Skriptlader (also der HubSpot-Tracking-Code) auf Ihrer Seite erstellt dieses Objekt für Sie, aber es ist möglicherweise nicht sofort verfügbar. Um den Zugriff auf die API zu verschieben, bis sie initialisiert ist, können Sie den window.hsConversationsOnReady
-Helfer verwenden. Im Folgenden finden Sie ein einfaches Beispiel:
SDK-Referenz
window.hsConversationsOnReady
Dies ist ein spezielles Feld, das Sie im window
-Objekt definieren können. Damit können Sie Code angeben, der ausgeführt wird, sobald das Widget verfügbar ist. Die Verwendung dieser Eigenschaft ist optional. Wenn sie verwendet wird, sollte dieses Feld auf ein Array von Funktionen festgelegt werden. Sobald die API initialisiert wurde, überprüft sie auf das Vorhandensein dieses Arrays und führt seine Funktionen der Treihe nach aus. Zum Beispiel:
hsConversationsSettings
Dieses Objekt ermöglicht es Ihnen, vor dem Initialisieren einige Konfigurationsoptionen für das Widget anzugeben. Die Verwendung dieses Objekts ist optional.
Feldname | Datentyp | Standard | Beschreibung |
---|---|---|---|
|
Boolesch | true | Ob das Widget implizit geladen werden oder gewartet werden soll, bis die widget.load -Methode aufgerufen wird |
inlineEmbedSelector |
Zeichenfolge | "" | Wo das Widget in der Seite eingebettet sein soll. Wenn ein Selektor (z. B. #some-id) angegeben wird, wird das Widget inline in diesem DOM-Knoten eingebettet. Es bleibt so lange offen, bis es über widget.remove entfernt wird |
enableWidgetCookieBanner |
Enumeration | false | Verhalten des Cookie-Banners für alle Chatflows auf der Seite steuern:false – Verwenden Sie die Einstellung von Chatflows (Standard)true – Aktivieren Sie Cookie-Banner, wenn das Widget geladen wirdON_WIDGET_LOAD – Wie „true“: aktivieren Sie Cookie-Banner, wenn das Widget geladen wirdON_EXIT_INTENT – Aktivieren Sie Cookie-Banner, wenn der Benutzer scheinbar die Seite verlassen will (Exit Intent)Beachten Sie, dass dieses Feld früher ein boolesches Feld war. Es kann nun sowohl die ursprünglichen Boolean -Werte als auch die aktualisierten enum -Werte aufnehmen. |
disableAttachment |
Boolesch | false | Ob die Schaltfläche zum Hochladen eines Anhangs im Chat-Widget ausgeblendet sein soll. |
Inline-Einbettungsstile
window.hsConversationsOnReady
Wenn das Widget auf einer vom Kunden festgelegten Stelle eingebettet wird, können mehrere DOM-Elemente hinzugefügt und den Anforderungen des Kunden (z. B. Höhe, Breite, Rand) entsprechend formatiert werden. Beachten Sie, dass diese Struktur nur angewendet wird, wenn Sie die inlineEmbedSelector
-Option verwenden.
<div id="hubspot-conversations-inline-parent">
<iframe id="hubspot-conversations-inline-iframe" />
</div>
Das Chat-Widget kann beispielsweise standardmäßig wie folgt aussehen:
Dieses gequetschte Layout ist nicht ideal, daher können Sie das Widget durch Berücksichtigen von Stilen wie diesem anpassen:
#hubspot-conversations-inline-iframe {
width: 300px;
height: 500px;
border:none;
}
Dies bietet ein sehr viel angenehmeres Benutzererlebnis.
HubSpotConversations.widget
Das Widget-Objekt enthält eine Reihe von Methoden, die es Ihnen ermöglichen, das Chat-Widget auf Ihrer Seite zu ändern.
widget.load
Lädt das Widget zum ersten Mal auf der Seite. Wenn das Widget derzeit geladen wird, sind die nachfolgenden Aufrufe dieser Methode Nulloperationen.
Diese Methode ist nur erforderlich, wenn Sie das loadImmediately
-Flag auf false
festlegen. Andernfalls lädt sich das Widget automatisch selbst.
Hinweis: widget.load
wird auf einen Aufruf pro Sekunde gedrosselt.
Parameter:
Feldname | Datentyp? | Standard | Beschreibung |
---|---|---|---|
widgetOpen |
Boolesch | false | Ob das Widget in einem offenen Zustand geladen werden soll |
widget.refresh
Aktualisiert unter Angabe der aktuellen Seiten-URL die Informationen des Widgets und stellt sie erneut dar.
Wenn sich das Chat-Widget auf einer Anwendung mit nur einer Seite befindet, kann diese Methode nützlich sein, um das Widget bei Routenänderungen zu aktualisieren. Dadurch können Sie unterschiedliche Chatflows auf verschiedenen Seitenrouten angeben. Wenn widget.refresh
auf einer Route aufgerufen wird, auf der kein Chatflow vorhanden ist, und der Benutzer nicht gerade in einer Konversation aktiv ist, wird das Widget entfernt.
Hinweis: widget.refresh
wird auf einen Aufruf pro Sekunde gedrosselt.
Parameter:
Feldname | Datentyp? | Standard | Beschreibung |
---|---|---|---|
openToNewThread |
Boolesch | false | Ob das Erstellen eines neuen Threads erzwungen werden soll |
Ein Beispiel für die Verwendung des optoNewThread
-Feldes finden Sie unter Öffnen eines bestimmten Chatflows auf der Seite.
Beispiel:
widget.close
Schließt das Widget. Wenn das Widget bereits geschlossen oder derzeit nicht geladen ist, ist dies eine Nulloperation.
Beispiel:
widget.remove
Entfernt das Widget von der Seite. Wenn das Widget nicht auf der Seite vorhanden ist, ist dies eine Nulloperation. Um das Widget erneut anzuzeigen, muss eine vollständige Seitenaktualisierung erfolgen, oder widget.load
kann aufgerufen werden.
Beispiel:
clear
Das Chat-Widget erstellt mehrere Cookies, um seinen Zustand über Website-Besuche und Seitenaktualisierungen hinweg beizubehalten. Der Bereich dieser Cookies ist auf die Domain der Seite angepasst, die das Widget hosten, und die Cookies werden zur Unterstützung der folgenden Eigenschaften verwendet:
- Verweisen auf historische Konversationen
- Fortsetzen des offenen Zustands des Chat-Widgets über das Laden von Seiten hinweg
- Fortsetzen des offenen Zustands der Willkommensnachricht über das Laden von Seiten hinweg
Die clear
-Methode kann verwendet werden, um diese Cookies zu löschen. Dabei kehrt das Widget bei nachfolgenden Ladevorgängen zu seinem Standardzustand zurück.
Die folgenden Cookies werden mit dieser Methode gelöscht:
messagesUtk
hs-messages-is-open
hs-messages-hide-welcome-message
Weitere Informationen zu diesen Cookies finden Sie in diesem Wissensdatenbank-Artikel.
Beispiel:
Sie können auch {resetWidget:true}
an die clear()
-Funktion übergeben, um alle Cookies im Zusammenhang mit Chats zu löschen, das Widget von der Seite zu entfernen und eine neue Instanz des Chat-Widgets zu erstellen.
Beispiel:
Event specification
Das Chat-Widget gibt verschiedene Events aus, auf die Sie während deren gesamten Lebenszyklus überwachen und reagieren können.
Unterstützte Events
conversationStarted
Wird ausgegeben, wenn eine neue Konversation erfolgreich gestartet wurde.
Event-Payload
Feldname | Datentyp | Beschreibung |
---|---|---|
conversation |
Konversation | Details zu der Konversation, die gestartet wurde |
Beispiel:
conversationClosed
Wird ausgegeben, wenn eine neue Konversation erfolgreich abgeschlossen wurde.
Hinweis: Dieses Event wird ausgelöst, wenn die Konversation vom Conversations-Postfach als abgeschlossen markiert ist, und ist unabhängig vom Benutzer, der das Widget minimiert oder schließt.
Event-Payload
Feldname | Datentyp | Beschreibung |
---|---|---|
conversation |
Konversation | Details zu der Konversation, die geschlossen wurde |
Beispiel:
unreadConversationCountChanged
Wird ausgegeben, wenn sich die Anzahl der Konversationen im Widget mit jeglichen ungelesenen Nachrichten ändert (Erhöhung oder Verringerung).
Event-Payload
Feldname | Datentyp | Beschreibung |
---|---|---|
unreadCount |
Zahl | Die neue Summe an Konversationen im Widget mit allen ungelesenen Nachrichten |
Beispiel:
contactAssociated
Wird ausgegeben, wenn der Besucher einem Kontakt im CRM zugeordnet ist.
Event-Payload
Feldname | Datentyp | Beschreibung |
---|---|---|
message |
Zeichenfolge | Eine Bestätigungsnachricht, dass der Besucher mit einem Kontakt verknüpft wurde |
Beispiel:
Vielen Dank, dass Sie Ihr Feedback mit uns geteilt haben.