Send Custom Events

Beyond the built-in events the assistant records automatically (session starts, queries, reactions, forms), you can send your own custom events from the page where the assistant is embedded. Custom events appear in the session timeline alongside the standard ones, so you can correlate visitor behavior on your site with the assistant conversation.

The `sendTrace` Method

The assistant instance exposes sendTrace:

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

Parameter	Type	Required	What it does
`eventName`	`string`	Yes	The name of the event — pick something descriptive, like `CTA.Clicked` or `Product.Viewed`.
`eventProperties`	`Record<string, string>`	No	Key–value pairs attached to the event. Use them to add context — a button ID, a page path, a product SKU.

Example: Track Reference Clicks with a Custom Helper

The natural way to send custom events is through a custom helper — a small JavaScript function you add in the Advanced editor and call from your templates. This keeps tracking logic alongside the rest of your assistant customization.

1. Create the helper. In the Advanced editor, add a new helper named trackReferenceClick:

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

2. Call it from a template. Override the highlighted template (or your own content-type template) and wire the helper to the link's onclick:

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

Every time a visitor clicks a reference card, a Reference.Clicked event is recorded in the session timeline with the reference ID and title.

3. Another example — track a product view. If your assistant uses a custom PRODUCT content-type template, add a helper named trackProductView:

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

Then fire it when the product card renders or when the visitor clicks it:

<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>

How It Works

The call sends the event over the assistant's SignalR connection to the

backend — no extra endpoint or API key is needed.

If you set userInformation in the embed options,

those properties are automatically included in the event (prefixed with user.), so you don't need to pass them again.

The event is recorded in the session timeline as a

Seekdown.CustomTrace entry, with your eventName and properties visible in the detail card.

When to Use It

Measure what visitors do with answers — track which reference cards they

click, which products they view, which links they follow.

Measure funnel steps — send events for each step (e.g. Pricing.Viewed,

Signup.Started, Signup.Completed) and later see which sessions include which steps.

Debug template interactions — fire a trace from a custom helper and

inspect it in the session timeline to verify that your template wiring works as expected.

Send Custom Events

The sendTrace Method

Example: Track Reference Clicks with a Custom Helper

How It Works

When to Use It

Related Docs

Still need help?

The `sendTrace` Method