Envía eventos personalizados

Además de los eventos integrados que el asistente registra automáticamente (inicios de sesión, consultas, reacciones, formularios), puedes enviar tus propios eventos personalizados, cada uno con las propiedades que le añadas, desde la página donde está integrado el asistente. Los eventos personalizados aparecen en el User Activity Feed y en la línea temporal de la sesión junto a los estándar, para que puedas relacionar el comportamiento de los visitantes en tu web con la conversación con el asistente y seguir exactamente el contexto que te interesa.

El método sendTrace

La instancia del asistente expone sendTrace:

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

Envía un evento con propiedades

Las propiedades son lo que hace útil el seguimiento personalizado: añade el contexto que quieras seguir, como pares clave-valor de tipo cadena. Llama a sendTrace desde cualquier script de la página donde está integrado el asistente: el manejador de un botón, un cambio de ruta, un paso del proceso de compra:

// 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"
});

Algunas cosas que conviene saber:

• Los valores son cadenas. Pasa cadenas y convierte a cadena todo lo demás:

String(count), price.toFixed(2). Las claves las eliges tú.

• Se envía y se olvida. La llamada devuelve una Promise, pero no necesitas hacer

await: si la conexión no está lista, falla en silencio en lugar de lanzar un error.

• Protege las llamadas muy tempranas. Si una traza puede dispararse antes de que el

widget se haya conectado, comprueba antes isConnected:

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

Qué pasa con tus propiedades

Una vez enviado, un evento lleva sus propiedades a todos los sitios donde la analítica puede leerlas:

• User Activity Feed: tus propiedades se muestran en la columna Details de la

fila del evento (consulta Sigue la actividad de los usuarios).

• Línea temporal de la sesión: aparecen en la tarjeta de detalle desplegable del

evento (consulta Revisa la línea temporal de una sesión).

• Exportación CSV: la exportación ActivityFeed las incluye, así que puedes

analizarlas en una hoja de cálculo o en una herramienta de BI.

Tu eventName se guarda y se muestra exactamente como lo escribiste (Pricing.Viewed), y cada propiedad que definas se conserva tal cual.

Nombres de propiedades reservados

Seekdown añade automáticamente a cada evento algunas propiedades de identidad y de enrutamiento. No las defines tú y no aparecen entre tus Details personalizados: en su lugar alimentan las columnas User, Source y Time y la agrupación por sesión:

Evita reutilizar estos nombres en tus propias propiedades. Todo lo demás que envíes se guarda tal cual y se muestra en Details.

Ejemplo: sigue los clics en referencias con un helper personalizado

La forma natural de enviar eventos personalizados es mediante un helper personalizado: una pequeña función de JavaScript que añades en el Advanced editor y llamas desde tus plantillas. Así la lógica de seguimiento queda junto al resto de la personalización de tu asistente.

1. Crea el helper. En el Advanced editor, añade un nuevo helper llamado trackReferenceClick:

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

2. Llámalo desde una plantilla. Sobrescribe la plantilla highlighted (o tu propia plantilla de tipo de contenido) y conecta el helper al onclick del enlace:

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

Cada vez que un visitante hace clic en una tarjeta de referencia, se registra un evento Reference.Clicked en la línea temporal de la sesión con el ID y el título de la referencia.

3. Otro ejemplo: sigue la vista de un producto. Si tu asistente usa una plantilla personalizada de tipo de contenido PRODUCT, añade un helper llamado trackProductView:

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

Después dispáralo cuando se renderice la tarjeta del producto o cuando el visitante haga clic en ella:

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

Cómo funciona

1. La llamada envía el evento al backend por la conexión SignalR del asistente: no hace

falta ningún endpoint adicional ni clave de API.

1. Si defines userInformation en las opciones de integración,

esas propiedades se incluyen automáticamente en el evento (con el prefijo user.), así que no tienes que volver a pasarlas.

1. El evento se registra con tu propio eventName y sus propiedades, y aparece tanto en

la línea temporal de la sesión como en el User Activity Feed.

Buenas prácticas

• Nombra los eventos como Dominio.Acción. Un esquema coherente (Pricing.Viewed,

Signup.Started, Reference.Clicked) mantiene el feed legible y agrupa los eventos relacionados.

• Mantén los nombres estables. El feed y el CSV agrupan por el nombre exacto del

evento: renombrar un evento divide su historial. Elige un nombre y mantenlo.

• Envía cadenas y que sean pequeñas. Unas pocas propiedades cortas y con sentido

son mejores que un bloque grande; convierte a cadena los números y los booleanos.

• No envíes secretos. Las trazas se guardan en tu analítica y se muestran en el

panel: nunca pongas en una propiedad contraseñas, tokens ni datos que no querrías que leyera un compañero.

Cuándo usarlo

• Mide qué hacen los visitantes con las respuestas: sigue en qué tarjetas de

referencia hacen clic, qué productos ven, qué enlaces siguen.

• Mide los pasos del embudo: envía eventos para cada paso (p. ej. Pricing.Viewed,

Signup.Started, Signup.Completed) y luego mira qué sesiones incluyen qué pasos.

• Depura las interacciones de las plantillas: dispara una traza desde un helper

personalizado y revísala en la línea temporal de la sesión para comprobar que el cableado de tu plantilla funciona como esperas.

Documentación relacionada

• Helpers
• Revisa la línea temporal de una sesión
• Integrar un asistente en una web