Ereignisse API Referenz

Hotjars Events-API ermöglicht es Ihnen, Ereignisse an Hotjar zu senden, wenn bestimmte Aktionen auf Ihrer Website stattfinden, und sie innerhalb von Hotjar als Ereignisse zu speichern. Diese Ereignisse können verwendet werden, um Ihnen bei der Filterung von gesammelten Aufnahmen und Heatmap-Daten zu helfen und um Sitzungsaufzeichnungen auszulösen, um Feedback-Widgets und Umfragen erscheinen zu lassen. 

• Übersicht
• Der Events-API-Aufruf
• Beispiele für Events-API-Aufrufe
• Best Practices
• Events testen

---

Übersicht

Hotjar-Events stellen Aktionen dar, die ein Benutzer während seines Besuchs auf Ihrer Website ausgeführt hat. Diese Ereignisse werden definiert und über Ihren Client-Code an Hotjar über die Hotjar-Events-API übermittelt. 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 könnte gesendet werden, sobald die Seite geladen wird, wenn ein Modal erscheint oder wenn sie eine bestimmte Variation des Inhalts durch einen A/B-Test sehen.

Zum Beispiel kann es nützlich sein, Benutzer zu verfolgen, die während des Bezahlvorgangs erfolgreich eine Kreditkarte hinzugefügt haben, indem Sie ein Ereignis wie Kreditkarte erfolgreich hinzugefügt hinzufügen. Sie könnten auch daran interessiert sein, Sitzungen zu vergleichen, in denen eine Kreditkarte nicht erfolgreich hinzugefügt wurde, indem Sie ein zweites Ereignis hinzufügen, wie Hinzufügen der Kreditkarte fehlgeschlagen. Indem Sie Ereignisse basierend auf Benutzeraktionen übergeben, können Sie Aufzeichnungen nach Benutzern filtern, die jedes dieser Ereignisse während ihres Bezahlvorgangs ausgelöst haben. Das Einrichten dieser Ereignisse im Code Ihrer Website könnte ähnlich aussehen wie folgt:

fetch('/api/kreditkarte-hinzufuegen', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(body),
})
.then((response) => response.json())
.then((data) => {
    hj('event', 'Kreditkarte erfolgreich hinzugefügt')
    // Backend-Antwort verarbeiten.
  }
)
.catch(error => {
  hj('event', 'Hinzufügen der Kreditkarte fehlgeschlagen')
})

*Konsultieren Sie Ihre eigenen Entwickler, um festzustellen, welcher Code für Ihre Website erforderlich ist.

Da die Kriterien für das Senden von Ereignissen auf Ihrem eigenen Code basieren, ist die Funktion sehr flexibel, erfordert jedoch benutzerdefinierte Codierung von Ihrem Webentwickler.

Zurück nach oben

Der Aufruf der Events-API

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

hj('event', 'Aktion_Name');

• Der erste Parameter sollte immer den Zeichenfolgenwert event enthalten.
• Der zweite Parameter ist der benutzerdefinierte Name, der Ihrem Ereignis zugewiesen ist. Im obigen Beispiel ist der Ereignisname Aktion_Name, aber dies kann beliebig gewählt werden. (Beispiel: 'Modal_geöffnet', 'Variante_A_angezeigt', usw.)

Beachten Sie die Einschränkungen bei der Implementierung von Ereignissen

• Benennen Ihrer Ereignisse.

  Der Ereignisname darf maximal 250 Zeichen nicht überschreiten und kann nur eine beliebige Kombination der folgenden Zeichen enthalten: alphanumerische Zeichen (a-z, A-Z, 0-9), Leerzeichen, Unterstriche (_), Bindestriche (-), Punkte (.), Doppelpunkte (:) und Schrägstriche (/).

• Es gibt ein Limit von 10.000 eindeutigen Ereignissen pro Hotjar-Website.

  Hotjar-Filter unterstützen nur 10.000 eindeutige Ereignisse pro Hotjar-Website, mit einer unbegrenzten Anzahl von Benutzern, die mit diesen Ereignissen verbunden sind. Wenn Sie dieses Limit überschreiten, können nur die 10.000 am häufigsten verwendeten Ereignisse (sortiert 0-9, a-Z) in der Benutzeroberfläche durchsucht werden. Dies ist ein fortlaufendes Gesamtkontingent, sodass nach Überschreiten des Limits einige vorhandene Ereignisse in der Filterung nicht mehr durchsuchbar sind. Wenn Sie das Limit überschreiten, können Sie Aufzeichnungen löschen, die Ereignisse enthalten, die Sie nicht mehr benötigen. Etwa 10 Minuten nach dem Löschen wird Ihre Ereignisfilterliste aktualisiert.

• Nur die ersten 50 eindeutigen Ereignisse in einer einzelnen Sitzung sind durch Filter durchsuchbar.
  Um die Leistung zu optimieren, bewertet Hotjar nur die ersten 50 eindeutigen Ereignisse in einer Sitzung, um festzustellen, ob eine Sitzung den Ereignisfilterkriterien entspricht. Das bedeutet, dass, wenn eine Sitzung 51 einzigartige Ereignisse enthält, das letzte einzigartige Ereignis, das während der Sitzung ausgelöst wurde, nicht erkannt wird, wenn Sie Aufzeichnungen basierend auf diesem Ereignis filtern. Alle 51 Ereignisse sind jedoch weiterhin im Wiedergabebildschirm jeder Sitzung sichtbar.

• Es ist derzeit nicht möglich, Ereigniseigenschaften mit dem Ereignis zu übergeben.

Zurück nach oben

Beispiele für Events-API-Aufrufe

Hier sind einige Beispielfälle für Ereignisse.

• 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 in Bezug auf einen bestimmten Fehler, damit Sie Ihre Aufzeichnungen 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 zu erfahren, wann ein Benutzer eine bestimmte Seitenvariante während eines A/B-Tests lädt.

  hj('event', 'variant_b_displayed');

Zurück nach oben

Beste Praktiken

• Geben Sie keine persönlich identifizierbaren Informationen als Ereignis weiter.

  Persönlich identifizierbare Informationen (PII) sollten niemals als Ereignisse in Hotjar verwendet werden. Wenn Sie Sitzungsdaten mit bestimmten Benutzern verknüpfen möchten, sollten Sie stattdessen die Funktion Benutzerattribute erkunden.

• Wenn Sie auch Identify-API-Aufrufe tätigen, müssen diese vor Event-API-Aufrufen ausgeführt werden.

  Sie möchten möglicherweise Ereignisse mit auf Benutzerattributen basierender Ausrichtung kombinieren, um Umfragen oder Feedback auszulösen. Um dies einzurichten, muss der Identify-API-Aufruf vor dem Event-API-Aufruf erfolgen, wobei mögliche asynchrone Aufrufe an andere Dienste berücksichtigt werden müssen. Wenn der Event-API-Aufruf ausgeführt wird, bevor der Identify-API-Aufruf abgeschlossen ist, wird das Umfrage- oder Feedback-Widget nicht angezeigt.

• Ereignisse können nicht verwendet werden, um E-Mail- oder IP-Adressen oder Zahlen mit 9 oder mehr Ziffern zu sammeln.

  Da es derzeit keine Möglichkeit gibt, unser Benutzersuchwerkzeug mit Ereignissen zu verwenden, können sie nicht verwendet werden, um E-Mails, IP-Adressen oder Zahlen mit 9 oder mehr Ziffern zu sammeln, um zu verhindern, dass Kreditkartennummern an Hotjar übermittelt werden. Diese Entscheidung basiert auf der Allgemeinen Datenschutzverordnung (DSGVO). Wenn Sie E-Mail-Adressen mit Einwilligung Ihres Benutzers und im Einklang mit der DSGVO sammeln möchten, können Sie dies mit Benutzerattributen tun.

• Der Hotjar-Tracking-Code muss geladen werden, bevor Ereignisse gesendet werden.

  Das hj()-Objekt kann erst aufgerufen werden, nachdem der Hotjar-Tracking-Code auf der Seite ausgeführt wurde. Wenn das Skript, das die Events-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 Event-API zugegriffen wird, bevor der Hotjar-Tracking-Code ausgeführt wurde, können Sie die folgende Codezeile hinzufügen, bevor der Event-API-Code aufgerufen wird:

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

• Für E-Commerce-Websites vermeiden Sie die Übermittlung spezifischer Produktinformationen.

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

• Seien Sie vorsichtig beim Senden von Werten aus Objekten wie GTM-Datenlayern.

  Diese enthalten oft mehr Daten als erwartet.

• Vermeiden Sie die Übermittlung von Daten wie Datum oder Zeitstempel.
• Vermeiden Sie die Übermittlung von Daten aus URLs wie Weiterempfehlungscodes.
• Vermeiden Sie die Übermittlung detaillierter Fehlerprotokolle.

Zurück nach oben

Ereignisse testen

Die folgenden Schritte ermöglichen es Ihnen zu bestätigen, ob Ihre Ereignis-API-Aufrufe erfolgreich von Hotjar empfangen werden. Wenn Sie mit Ihrer Browserkonsole oder den Entwicklertools nicht vertraut sind, ziehen Sie in Betracht, ein Teammitglied hinzuzuziehen, das über mehr Kenntnisse in diesen Tools verfügt, oder einen Webentwickler um Unterstützung zu bitten.

Aktivieren Sie Hotjar-Debug-Logs in Ihrer Browserkonsole.

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

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

Öffnen Sie die Browserkonsole.

Wenn Sie mit den Entwicklertools Ihres Browsers oder der Konsole nicht vertraut sind, schauen Sie sich diesen Leitfaden an, um zu erfahren, wie Sie die Browserkonsole öffnen.

Lösen Sie das Ereignis manuell aus.

Um das Ereignis manuell auszulösen, fügen Sie den Event-API-Code in Ihre Browserkonsole ein und drücken Sie die Eingabetaste oder Return-Taste auf Ihrer Tastatur. Wenn das Ereignis erfolgreich ausgelöst wurde, sehen Sie eine Bestätigungsprotokollmeldung ähnlich dieser:

Wir empfehlen außerdem, dass Sie die Schritte durchgehen, 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 ist.

Wenn dasselbe Ereignis erkannt wird, wenn es manuell ausgelöst wird, aber nicht automatisch beim Testen der Benutzerreise, müssen Sie möglicherweise Ihren Code und die Kriterien überprüfen, die bestimmen, wann der Event-API-Aufruf gesendet wird.

Zurück nach oben