Eigene Events senden

Über die integrierten Events hinaus, die der Assistent automatisch aufzeichnet (Sitzungsstarts, Anfragen, Reaktionen, Formulare), können Sie von der Seite, auf der der Assistent eingebettet ist, eigene Events senden – jeweils mit beliebigen Eigenschaften, die Sie anhängen. Eigene Events erscheinen im User Activity Feed und in der Sitzungszeitleiste neben den Standard-Events, sodass Sie das Verhalten von Besuchern auf Ihrer Website mit der Unterhaltung mit dem Assistenten in Beziehung setzen und genau den Kontext verfolgen können, der Ihnen wichtig ist.

Die Methode sendTrace

Die Instanz des Assistenten stellt sendTrace bereit:

await window.skdwn.instance.sendTrace(eventName, eventProperties);

Ein Event mit Eigenschaften senden

Erst die Eigenschaften machen eigenes Tracking nützlich: Hängen Sie als String-Schlüssel-Wert-Paare jeden Kontext an, den Sie verfolgen möchten. Rufen Sie sendTrace aus einem beliebigen Skript auf der Seite auf, auf der der Assistent eingebettet ist – einem Button-Handler, einem Routenwechsel, einem Checkout-Schritt:

// Fire from your own page code — no API key, no extra endpoint needed.
window.skdwn.instance.sendTrace("Pricing.Viewed", {
  plan: "pro",
  billing: "annual",
  source: "hero-cta"
});

Einige Dinge, die Sie wissen sollten:

• Werte sind Strings. Übergeben Sie Strings; wandeln Sie alles andere um –

String(count), price.toFixed(2). Die Schlüssel wählen Sie selbst.

• Es ist Fire-and-forget. Der Aufruf gibt ein Promise zurück, Sie müssen es aber

nicht mit await abwarten – ist die Verbindung nicht bereit, schlägt er still fehl, statt eine Ausnahme auszulösen.

• Sichern Sie sehr frühe Aufrufe ab. Wenn ein Trace ausgelöst werden könnte, bevor

das Widget verbunden ist, prüfen Sie zuerst isConnected:

if (window.skdwn?.instance?.isConnected) {
  window.skdwn.instance.sendTrace("Pricing.Viewed", { plan: "pro" });
}

Was mit Ihren Eigenschaften passiert

Einmal gesendet, trägt ein Event seine Eigenschaften überallhin, wo Analysen sie lesen können:

• User Activity Feed – Ihre Eigenschaften erscheinen direkt in der Spalte

Details der Event-Zeile (siehe Nutzeraktivität verfolgen).

• Sitzungszeitleiste – sie erscheinen in der aufklappbaren Detailkarte des Events

(siehe Die Zeitleiste einer Sitzung prüfen).

• CSV-Export – der Export ActivityFeed enthält sie, sodass Sie sie in einer

Tabellenkalkulation oder einem BI-Tool auswerten können.

Ihr eventName wird genau so gespeichert und angezeigt, wie Sie ihn geschrieben haben (Pricing.Viewed), und jede gesetzte Eigenschaft bleibt unverändert erhalten.

Reservierte Eigenschaftsnamen

Seekdown hängt jedem Event automatisch einige Identitäts- und Routing-Eigenschaften an. Sie setzen diese nicht selbst, und sie erscheinen nicht unter Ihren eigenen Details – stattdessen speisen sie die Spalten User, Source und Time sowie die Gruppierung nach Sitzung:

Verwenden Sie diese Namen nicht für Ihre eigenen Eigenschaften. Alles andere, was Sie senden, wird unverändert gespeichert und unter Details angezeigt.

Beispiel: Klicks auf Referenzen mit einem eigenen Helper verfolgen

Der natürliche Weg, eigene Events zu senden, ist ein eigener Helper – eine kleine JavaScript-Funktion, die Sie im Advanced editor hinzufügen und aus Ihren Templates aufrufen. So bleibt die Tracking-Logik beim Rest Ihrer Assistenten-Anpassungen.

1. Den Helper erstellen. Fügen Sie im Advanced editor einen neuen Helper namens trackReferenceClick hinzu:

(referenceId, referenceTitle) => {
  window.skdwn.instance.sendTrace("Reference.Clicked", {
    referenceId: referenceId,
    referenceTitle: referenceTitle
  });
}

2. Aus einem Template aufrufen. Überschreiben Sie das Template highlighted (oder Ihr eigenes Inhaltstyp-Template) und binden Sie den Helper an das onclick des Links:

<a href="{{ reference.url }}"
   target="_blank"
   onclick="skdwn.instance.helpers.trackReferenceClick(
     '{{ reference.id }}',
     '{{ reference.title \| sanitize }}'
   )">
  {{ reference.title }}
</a>

Jedes Mal, wenn ein Besucher auf eine Referenzkarte klickt, wird ein Reference.Clicked-Event mit der ID und dem Titel der Referenz in der Sitzungszeitleiste aufgezeichnet.

3. Ein weiteres Beispiel – einen Produktaufruf verfolgen. Wenn Ihr Assistent ein eigenes Inhaltstyp-Template PRODUCT verwendet, fügen Sie einen Helper namens trackProductView hinzu:

(productId, category) => {
  window.skdwn.instance.sendTrace("Product.Viewed", {
    productId: productId,
    category: category
  });
}

Lösen Sie ihn dann aus, wenn die Produktkarte gerendert wird oder der Besucher darauf klickt:

<div class="product-card"
     onclick="skdwn.instance.helpers.trackProductView(
       '{{ reference.id }}',
       '{{ reference.dataset \| sanitize }}'
     )">
  <h4>{{ reference.title }}</h4>
  <a href="{{ reference.url }}">View product</a>
</div>

So funktioniert es

1. Der Aufruf sendet das Event über die SignalR-Verbindung des Assistenten an das

Backend – kein zusätzlicher Endpunkt und kein API-Schlüssel nötig.

1. Wenn Sie userInformation in den Einbettungsoptionen

festlegen, werden diese Eigenschaften automatisch in das Event aufgenommen (mit dem Präfix user.), sodass Sie sie nicht erneut übergeben müssen.

1. Das Event wird unter Ihrem eigenen eventName mit seinen Eigenschaften

aufgezeichnet und erscheint sowohl in der Sitzungszeitleiste als auch im User Activity Feed.

Best Practices

• Benennen Sie Events nach dem Schema Domain.Action. Ein einheitliches Schema

(Pricing.Viewed, Signup.Started, Reference.Clicked) hält den Feed lesbar und gruppiert zusammengehörige Events.

• Halten Sie Namen stabil. Feed und CSV gruppieren nach dem exakten Event-Namen –

eine Umbenennung teilt die Historie eines Events auf. Wählen Sie einen Namen und bleiben Sie dabei.

• Senden Sie Strings und halten Sie sie klein. Eine Handvoll kurzer, aussagekräftiger

Eigenschaften ist besser als ein großer Datenblock; wandeln Sie Zahlen und Booleans in Strings um.

• Senden Sie keine Geheimnisse. Traces werden in Ihren Analysen gespeichert und im

Dashboard angezeigt – legen Sie niemals Passwörter, Tokens oder Daten in eine Eigenschaft, die ein Teammitglied nicht lesen soll.

Wann Sie es nutzen

• Messen, was Besucher mit Antworten tun – verfolgen Sie, welche Referenzkarten sie

anklicken, welche Produkte sie ansehen, welchen Links sie folgen.

• Funnel-Schritte messen – senden Sie Events für jeden Schritt (z. B.

Pricing.Viewed, Signup.Started, Signup.Completed) und sehen Sie später, welche Sitzungen welche Schritte enthalten.

• Template-Interaktionen debuggen – lösen Sie einen Trace aus einem eigenen Helper

aus und prüfen Sie ihn in der Sitzungszeitleiste, um sicherzustellen, dass Ihre Template-Verdrahtung wie erwartet funktioniert.

Verwandte Dokumente

• Helper
• Die Zeitleiste einer Sitzung prüfen
• Einen Assistenten auf einer Website einbetten