Besucheridentifikation

ÜberblickEndpunkt
APPLICABLE PRODUCTS
  • Marketing Hub
    • Professional or Enterprise
  • Sales Hub
    • Professional or Enterprise
  • Service Hub
    • Professional or Enterprise
  • CMS Hub
    • Professional or Enterprise
Use the Visitor Identification API to identify visitors to your site that were authenticated using your own external authentication system.
 
An identification token returned from this API can be used to pass information about your already-authenticated visitor to the chat widget, so that it treats the visitor as a known contact. Agents in the inbox can then have confidence about who they are talking to, and visitors can access previous thread history across devices. For example:

Please note:

  • The Visitor Identification API is for telling HubSpot who the visitor is. You should not rely on this to authenticate users in your platform.
  • Access to the Visitor Identification API requires a Professional or Enterprise level subscription. If the account does not have a qualifying subscription, you will receive a 403 error response from the API.

Beispiel für einen Integrationsprozess

Um mit dieser Funktion zu integrieren, müssen Sie über eine vorhandene Webanwendung mit einem Authentifizierungssystem verfügen. 

Bevor Sie loslegen, stellen Sie sicher, dass Sie eine private App eingerichtet haben und der Account, den Sie zu integrieren versuchen, über ein qualifizierendes Professional- oder Enterprise-Abonnement verfügt.
 
Hier ist ein Beispiel für einen möglichen Integrationsprozess:
Möglicher Benutzeridentifikationsprozess
Sobald Ihr Kunde in Ihrem System angemeldet und verifiziert ist, führen Sie die folgenden Schritte aus, um ihn im Live-Chat zu identifizieren.

1. Legen Sie in Ihrem Frontend loadUnmittelbar im hsConversationsSettings-Objekt im Fenster auf false fest. Wenn Sie dies nicht tun, kann das Chat-Widget geladen werden, bevor die Identifikationsinformationen weitergegeben werden. Weitere Informationen zur API finden Sie unten im Chat-Widget-SDK-Primer.

  • Legen Sie die hsConversationsSettings-Eigenschaften außerhalb derisConversationsAPIReady-Funktion fest.
  • Außerdem müssen die hsConversationsSettings vor dem Aufruf festgelegt werden, andernfalls kann es vorkommen, dass eine Wettlaufsituation die Widget-Last beeinträchtigt.
window.hsConversationsSettings = { loadImmediately: false };

2. Generieren Sie ein Token von der API für die Besucheridentifikation, indem Sie die E-Mail-Adresse Ihres authentifizierten Besuchers übergeben. Dies sollte im Backend Ihrer Webanwendung erfolgen. Eine Beispielanfrage finden Sie auf der Registerkarte „Endpunkte“.

curl --request POST \ --url 'https://api.hubspot.com/conversations/v3/visitor-identification/tokens/create \ --data '{ "email": "gob@bluth.com", "firstName": "Gob", "lastName": "Bluth" }'
The provided first and last name will be set on the contact record in HubSpot after the chat begins if:
  • it's a new contact created by the Visitor Identification API.
  • it's an existing contact where the name is not already known.

This can be useful when personalizing messages to identified visitors when your external system already has name information, but it does not yet exist in HubSpot. These are optional parameters and not required. 

3. Legen Sie mit dem Token von Schritt 2 die folgenden Eigenschaften für das hsConversationsSettings-Objekt im Fenster fest.

window.hsConversationsSettings = { identificationEmail: "visitor-email@example.com", identificationToken: "<TOKEN FROM STEP 1>" };

4. Laden Sie das Widget.

window.HubSpotConversations.widget.load();

Das Token und die E-Mail müssen bei jedem Laden für einen authentifizierten Besucher im hsConversationsSettings-Objekt im Fenster festgelegt werden. Dieser Kontext wird nicht automatisch über Seitenladevorgänge übertragen, wenn diese Parameter nicht mehr festgelegt sind. Token bestehen vorübergehend und laufen nach 12 Stunden ab. Token können, solange sie mindestens alle 12 Stunden aktualisiert werden, zwischengespeichert werden, um zu vermeiden, dass das Token bei jedem Laden der Seite erneut abgerufen wird. 

Die Integration verifizieren

Sobald Sie Ihre Integration der Besucheridentifikationsfunktion abgeschlossen haben, können Sie überprüfen, ob sie wie erwartet funktioniert. Dies kann auf zwei Arten geschehen, je nach Ihrer Implementierung, sodass Sie die folgenden Beispiele möglicherweise an Ihre spezifischen Anforderungen anpassen müssen.

  • Wenn Sie das Chat-Widget für eine oder mehrere öffentlichen Seiten sowie hinter einem Authentifizierungssystem hinzugefügt haben:
    • Gehen Sie zu einer Seite, auf der das Chat-Widget keine Besucher identifiziert und eine Konversation startet.
    • Öffnen Sie in HubSpot das Postfach und verifizieren Sie, dass der gerade eingegangene Chat in die Kategorie „Unbekannter Besucher“ fällt. Wenn dies nicht der Fall ist, versuchen Sie, diese Schritte in einem privaten Browserfenster durchzuführen.
      • Gehen Sie zu einer Seite, auf der das Chat-Widget Besucher über die API für die Besucheridentifikation identifiziert und eine Konversation startet.
      • Öffnen Sie in HubSpot das Postfach und verifizieren Sie, dass der Chat korrekt dem Kontakt zugeordnet ist, unter dem Sie angemeldet sind. Sie sollten neben dem Namen des Kontakts ein Abzeichen sehen, das angibt, dass dieser Kontakt über diese API erfolgreich identifiziert wurde.

        visitor_identity_badge
  • Wenn Sie das Chat-Widget nur für Seiten hinter einem Authentifizierungssystem hinzugefügt haben und Zugriff auf mehrere Testbenutzer-Accounts haben:
    • Melden Sie sich als erster Testbenutzer bei HubSpot an, gehen Sie dann zu einer Seite, auf der das Chat-Widget geladen wird, und starten Sie eine Konversation.
    • Melden Sie sich von HubSpot ab und als zweiter Testbenutzer wieder an. Gehen Sie zu einer Seite, auf der das Chat-Widget geladen wird, und beginnen Sie eine Konversation.
    • Öfnnen Sie dann in HubSpot das Postfach und verifizieren Sie, ob die eingegangenen Chats vom ersten bzw. zweitenTest-Account stammen und ob Sie das Abzeichen neben den Kontaktnamen für beide Datensätze sehen.

Please note: for visitors identified with this API, HubSpot will not drop the messagesUtk cookie. HubSpot will also skip any email capture questions since email address is already known. Because the messagesUtk cookie and email capture do not apply to these chats, the associated settings in the chatflow will not show for visitors identified through the Visitor Identification API.

Chat-Widget SDK-Primer

Die API befindet sich im  window.HubSpotConversations-Objekt. Alle verfügbaren Methoden können über dieses Objekt aufgerufen werden. Der HubSpot-Skriptlader 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. Zum Beispiel:

<script type="text/javascript"> function onConversationsAPIReady() { console.log(`HubSpot Conversations API: ${window.HubSpotConversations}`); } /* configure window.hsConversationsSettings if needed. */ window.hsConversationsSettings = {}; /* If external API methods are already available, use them. */ if (window.HubSpotConversations) { onConversationsAPIReady(); } else { /* Otherwise, callbacks can be added to the hsConversationsOnReady on the window object. These callbacks will be called once the external API has been initialized. */ window.hsConversationsOnReady = [onConversationsAPIReady]; } </script>

SDK reference

window.hsConversationsOnReady array

This is an optional field you can define on the window object that enables you to specify code to be executed as soon as the widget becomes available. Once the API has been initialized, it will check for the existence of this array and execute its functions in series.

if (window.HubSpotConversations) { console.log('The api is ready already'); } else { window.hsConversationsOnReady = [ () => { console.log('Now the api is ready'); }, ]; }

hsConversationsSettings-Objekt

Dieses Objekt ermöglicht es Ihnen, vor dem Initialisieren einige Konfigurationsoptionen für das Widget anzugeben. Um die Besucheridentifikationsfunktion verwenden zu können, müssen Sie die folgenden Felder festlegen:

Use this table to describe parameters / fields
ParameterTypeDescription Default
loadImmediately
boolean

Ob das Widget implizit geladen werden oder gewartet werden soll, bis die widget.load-Methode aufgerufen wird

 true
identificationToken
string

Wird für die Integration mit der API für die Besucheridentifikation verwendet. Dies ist das Token, das vom Tokengenerierungsendpunkt auf der API für die Besucheridentifikation bereitgestellt wird und als Nachweis dafür dient, dass dieser Besucher identifiziert wurde.

 ""
identificationEmail
string

Die E-Mail-Adresse des Besuchers, den Sie als Person identifiziert haben, die das Widget lädt.

 ""
window.hsConversationsSettings = { loadImmediately: false, identificationEmail: "visitor-email@example.com", identificationToken: "<TOKEN FROM STEP 1>" };

Erfahren Sie mehr über das Conversations SDK.

War dieser Artikel hilfreich?
Dieses Formular dient dazu, Feedback zu unserer Entwicklerdokumentation zu sammeln. Wenn Sie uns Ihre Meinung zu HubSpot-Produkten mitteilen möchten, teilen Sie diese bitte im Ideenforum der Community.