API Events-Referenz

Mit der Hotjar-Events-API können Sie mithilfe von JavaScript Event an Hotjar senden, wenn bestimmte Aktionen auf Ihrer Website stattfinden, und diese in Hotjar als Events speichern. Diese Event können verwendet werden, um gesammelte Recordings und Heatmap-Daten zu filtern und um den Start der Sitzungserfassung oder das Erscheinen von Feedback-Widgets und Umfragen auszulösen.

• Übersicht
• Der Event-API-Aufruf
• Beispiele für den Aufruf der Ereignis-API
• Bewährte Praktiken
• Testen von Eventn

Überblick

Hotjar-Event stellen Aktionen dar, die ein Nutzer während seines Besuchs auf Ihrer Website durchgeführt hat. Diese Event werden über Ihren clientseitigen Code über die Hotjar-Ereignis-API definiert und an Hotjar weitergeleitet. Diese API ist auf allen Seiten verfügbar, die den Hotjar-Tracking-Code enthalten.

Mit JavaScript können Sie Ihre eigenen Kriterien festlegen, um zu bestimmen, welche Art von Aktion dazu führt, dass ein Ereignis an Hotjar gesendet wird. Das Ereignis kann gesendet werden, sobald die Seite geladen wird, wenn Benutzer auf eine bestimmte Schaltfläche klicken oder wenn sie eine bestimmte Variante des Inhalts in einem A/B-Test sehen.

Es kann zum Beispiel nützlich sein, Nutzer, die auf einen CTA-Button geklickt haben, mit einem Ereignis zu verfolgen. Vielleicht sind Sie daran interessiert, herauszufinden, warum die Nutzer nicht darauf klicken. Durch die Übergabe eines Events können Sie die Recordings nach Benutzern filtern, die nicht auf Ihre Aufforderung zur Handlung geklickt haben. Wenn Sie dies im Code Ihrer Website einrichten, könnte das etwa so aussehen:

document.querySelector('#meine-schaltfläche')
	.addEventListener('click', () => hj('event', 'clicked_cta'));

Da die Kriterien für das Senden von Eventn auf Ihrem eigenen Code basieren, ist die Funktion sehr flexibel, kann aber eine individuelle Codierung durch Ihren Webentwickler erfordern.

Zurück zum Anfang

Der Aufruf der Ereignis-API

Im Folgenden finden Sie das grundlegende Format für einen Aufruf der Ereignis-API:

hj('event', 'action_name');

• Der erste Parameter sollte immer den String-Wert event enthalten.
• Der zweite Parameter ist der benutzerdefinierte Name, der Ihrem Ereignis zugewiesen wurde. Im obigen Beispiel lautet der Name des Events action_name, er kann jedoch beliebig gewählt werden. (Beispiel: 'cta_click', 'opened_modal', 'shown_variant_a', usw.)

Beachten Sie die Einschränkungen bei der Implementierung von Eventn

• Benennen Sie Ihre Event.

  Der Ereignisname darf nicht länger als 250 Zeichen sein und darf nur alphanumerische Zeichen (a-z, A-Z, 0-9), Unterstriche (_) und Bindestriche (-) enthalten.

• Es gibt eine Grenze von 10.000 eindeutigen Eventn pro Hotjar-Website.

  Hotjar-Filter unterstützen nur 10.000 eindeutige Event pro Hotjar-Website mit einer unbegrenzten Anzahl von Benutzern, die mit diesen Eventn verbunden sind. Wenn Sie diesen Wert überschreiten, werden nur 10.000 der meistgenutzten Event (sortiert von 0-9, a-Z) in der Schnittstelle durchsuchbar sein. Es handelt sich dabei um eine gleitende Gesamtzahl, so dass nach Überschreiten des Limits einige vorhandene Event möglicherweise nicht mehr im Filter durchsuchbar sind. Wenn Sie das Limit überschreiten, können Sie Recordings löschen, die nicht mehr benötigte Event enthalten. Etwa 10 Minuten nach dem Löschen wird Ihre Ereignisfilterliste aktualisiert.

• Derzeit ist es nicht möglich, Ereigniseigenschaften mit dem Ereignis zu übergeben.

Zurück zum Anfang

Beispiele für Ereignis-API-Aufrufe

Im Folgenden finden Sie einige Beispiele für die Verwendung von Eventn.

• Senden Sie ein Ereignis an Hotjar, das Sie verwenden können, um eine Umfrage auszulösen, wenn ein Benutzer auf eine Schaltfläche "Abonnieren" klickt.

  hj('event', 'subscribed_to_email_list');
  

• Senden Sie ein Ereignis an Hotjar, das sich auf einen bestimmten Fehler bezieht, so dass Sie Ihre Recordings nach Benutzern filtern können, die während ihrer Sitzung auf einen Fehler gestoßen sind.

  hj('event', 'error_occurred');
  

• Senden Sie ein Ereignis an Hotjar, um Sie zu informieren, wenn ein Nutzer während eines A/B-Tests eine bestimmte Seitenvariante lädt.

  hj('event', 'variant_b_displayed');

Zurück zum Anfang

Bewährte Praktiken

• Übergeben Sie keine persönlichen Informationen als Ereignis.

  Persönliche Identifikationsdaten (PII) sollten niemals als Event in Hotjar verwendet werden. Wenn Sie Sitzungsdaten mit bestimmten Benutzern verknüpfen möchten, sollten Sie stattdessen die Funktion Benutzerattribute verwenden.

• Wenn Sie auch Identify-API-Aufrufe durchführen, müssen diese vor Ereignis-API-Aufrufen ausgeführt werden.

  Möglicherweise möchten Sie Event mit der auf Benutzerattributen basierenden Zielgruppenansprache kombinieren, um Umfragen oder Feedbacks auszulösen. Um dies einzurichten, muss der Identify-API-Aufruf vor dem Ereignis-API-Aufruf ausgeführt werden, wobei alle asynchronen Aufrufe an andere Dienste zu berücksichtigen sind. Wenn der Ereignis-API-Aufruf ausgeführt wird, bevor der Identify-API-Aufruf die Ausführung beendet hat, wird das Umfrage- oder Feedback-Widget nicht angezeigt.

• Event können nicht verwendet werden, um E-Mail- oder IP-Adressen oder Nummern mit 9 oder mehr Ziffern zu erfassen.

  Da es derzeit keine Möglichkeit gibt, unser User-Lookup-Tool mit Eventn zu verwenden, können diese nicht zum Erfassen von E-Mails, IP-Adressen oder Zahlen mit 9 oder mehr Ziffern verwendet werden, um zu verhindern, dass Kreditkartennummern an Hotjar übermittelt werden. Diese Entscheidung basiert auf der General Data Protection Regulation (GDPR). Wenn Sie mit dem Einverständnis Ihrer Nutzer und in Übereinstimmung mit der GDPR E-Mail-Adressen sammeln möchten, können Sie dies mit Benutzerattributen tun.

• Der Hotjar Tracking Code muss vor dem Senden von Events geladen werden.

  Auf das hj()-Objekt kann erst dann zugegriffen werden, wenn der Hotjar-Tracking-Code auf der Seite ausgeführt wurde. Wenn das Skript, das die Ereignis-API aufruft, vor Ihrem Hotjar-Tracking-Code hinzugefügt wird, tritt ein Fehler auf und das Ereignis wird nicht erkannt. Wenn aus irgendeinem Grund auf die Ereignis-API zugegriffen wird, bevor der Hotjar Tracking-Code ausgeführt wurde, können Sie die folgende Codezeile hinzufügen, bevor der Ereignis-API-Code aufgerufen wird:

  window.hj=window.hj||function(){(hj.q=hj.q||[]).push(arguments);};

• Vermeiden Sie bei E-Commerce-Websites die Übermittlung spezifischer Produktinformationen.

  Dazu gehören Informationen wie SKU-Codes. Normalerweise sind URLs nützlicher und werden standardmäßig erfasst.

• Seien Sie vorsichtig, wenn Sie Werte von Objekten wie GTM-Datenebenen senden.

  Diese enthalten oft mehr Daten, als Sie erwarten.

• Vermeiden Sie die Übergabe von Datumsangaben oder Zeitstempeln.
• Vermeiden Sie die Übergabe von URLs wie z.B. Referral Codes.
• Vermeiden Sie die Übergabe von detaillierten Fehlerprotokollen.

Zurück zum Anfang

Testen von Eventn

Anhand der folgenden Schritte können Sie überprüfen, ob Ihre API-Aufrufe für Event erfolgreich von Hotjar empfangen werden. Wenn Sie mit Ihrer Browserkonsole oder den Entwickler-Tools nicht vertraut sind, sollten Sie ein Teammitglied, das sich mit diesen Tools besser auskennt, oder einen Webentwickler zur Hilfe hinzuziehen.

Aktivieren Sie die Hotjar-Debug-Protokolle in Ihrer Browserkonsole.

Öffnen Sie die Seite, auf der Sie das Ereignis testen möchten, und fügen Sie den Parameter ?hjDebug=1 an das Ende der URL an. Hier sind ein paar Beispiele, wie das aussehen könnte:

https://www.example.com/?hjDebug=1
ODER
 https://www.example.com/?utm_1234&hjDebug=1

Öffnen Sie die Konsole Ihres Browsers.

Wenn Sie mit den Entwickler-Tools Ihres Browsers oder der Konsole nicht vertraut sind, lesen Sie diese Anleitung, um zu erfahren, wie Sie die Konsole Ihres Browsers öffnen.

Lösen Sie das Ereignis manuell aus.

Um Ihr Ereignis manuell auszulösen, fügen Sie den Ereignis-API-Code in Ihre Browserkonsole ein und drücken Sie die Eingabetaste oder den Zeilenschalter auf Ihrer Tastatur. Wenn das Ereignis erfolgreich ausgelöst wurde, wird ein Bestätigungsprotokoll ähnlich diesem angezeigt:

Wir empfehlen auch, dass Sie die Schritte durchführen, die Ihr Benutzer durchführen würde, um das Ereignis automatisch auszulösen. Wenn das Ereignis automatisch ausgelöst wird, wissen Sie, dass Ihr Code erfolgreich implementiert wurde.

Wenn dasselbe Ereignis manuell ausgelöst wird, aber nicht automatisch, wenn Sie die Benutzerreise testen, müssen Sie möglicherweise Ihren Code und die Kriterien überarbeiten, die bestimmen, wann der Ereignis-API-Aufruf gesendet wird.

Zurück zum Anfang