Inviare eventi personalizzati

Oltre agli eventi integrati che l’assistente registra automaticamente (inizi di sessione, domande, reazioni, moduli), puoi inviare i tuoi eventi personalizzati, ciascuno con le proprietà che vuoi associare, dalla pagina in cui l’assistente è integrato. Gli eventi personalizzati compaiono nello User Activity Feed e nella timeline della sessione insieme a quelli standard, così puoi correlare il comportamento dei visitatori sul tuo sito con la conversazione con l’assistente e seguire esattamente il contesto che ti interessa.

Il metodo sendTrace

L’istanza dell’assistente espone sendTrace:

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

Inviare un evento con proprietà

Le proprietà sono ciò che rende utile il tracciamento personalizzato: associa qualsiasi contesto tu voglia seguire, come coppie chiave–valore di tipo stringa. Chiama sendTrace da qualsiasi script della pagina in cui l’assistente è integrato: un gestore di pulsante, un cambio di route, un passaggio del checkout:

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

Alcune cose da sapere:

• I valori sono stringhe. Passa stringhe; converti in stringa tutto il resto: String(count),

price.toFixed(2). Le chiavi le scegli tu.

• È "fire-and-forget". La chiamata restituisce una Promise, ma non devi

attenderla con await: se la connessione non è pronta, fallisce silenziosamente invece di generare un errore.

• Proteggi le chiamate molto anticipate. Se una traccia potrebbe partire prima che il widget si sia

connesso, controlla prima isConnected:

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

Cosa succede alle tue proprietà

Una volta inviato, un evento porta con sé le sue proprietà ovunque le analisi possano leggerle:

• User Activity Feed: le tue proprietà compaiono in linea nella colonna Details

della riga dell’evento (vedi Monitorare l’attività degli utenti).

• Timeline della sessione: compaiono nella scheda di dettaglio espandibile dell’evento (vedi

Esaminare la timeline di una sessione).

• Esportazione CSV: l’esportazione ActivityFeed le include, così puoi analizzarle

in un foglio di calcolo o in uno strumento di BI.

Il tuo eventName viene memorizzato e mostrato esattamente come l’hai scritto (Pricing.Viewed), e ogni proprietà che imposti viene conservata così com’è.

Nomi di proprietà riservati

Seekdown associa automaticamente ad ogni evento alcune proprietà di identità e di instradamento. Non sei tu a impostarle e non compaiono tra i tuoi Details personalizzati: alimentano invece le colonne User, Source e Time e il raggruppamento per sessione:

Evita di riutilizzare questi nomi per le tue proprietà. Tutto il resto che invii viene memorizzato così com’è e mostrato in Details.

Esempio: tracciare i clic sui riferimenti con un helper personalizzato

Il modo naturale per inviare eventi personalizzati è tramite un helper personalizzato: una piccola funzione JavaScript che aggiungi nell’Advanced editor e richiami dai tuoi template. Così la logica di tracciamento resta accanto al resto della personalizzazione dell’assistente.

1. Crea l’helper. Nell’Advanced editor, aggiungi un nuovo helper chiamato trackReferenceClick:

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

2. Richiamalo da un template. Sostituisci il template highlighted (o il tuo template per tipo di contenuto) e collega l’helper all’onclick del link:

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

Ogni volta che un visitatore fa clic su una scheda di riferimento, nella timeline della sessione viene registrato un evento Reference.Clicked con l’ID e il titolo del riferimento.

3. Un altro esempio: tracciare la visualizzazione di un prodotto. Se il tuo assistente usa un template personalizzato per il tipo di contenuto PRODUCT, aggiungi un helper chiamato trackProductView:

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

Poi attivalo quando la scheda prodotto viene visualizzata o quando il visitatore ci fa clic:

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

Come funziona

1. La chiamata invia l’evento al backend tramite la connessione SignalR

dell’assistente: non servono endpoint aggiuntivi né chiavi API.

1. Se imposti userInformation nelle opzioni di integrazione,

quelle proprietà vengono incluse automaticamente nell’evento (con il prefisso user.), quindi non devi passarle di nuovo.

1. L’evento viene registrato con il tuo eventName, insieme alle sue proprietà, e

compare sia nella timeline della sessione sia nello User Activity Feed.

Buone pratiche

• Dai agli eventi nomi Dominio.Azione. Uno schema coerente (Pricing.Viewed,

Signup.Started, Reference.Clicked) mantiene il feed leggibile e raggruppa gli eventi correlati.

• Mantieni stabili i nomi. Il feed e il CSV raggruppano per nome esatto dell’evento: rinominare

un evento ne divide lo storico. Scegli un nome e mantienilo.

• Invia stringhe e mantienile brevi. Poche proprietà brevi e significative

valgono più di un grosso blocco di dati; converti in stringa numeri e booleani.

• Non inviare segreti. Le tracce vengono memorizzate nelle tue analisi e mostrate nella

dashboard: non inserire mai in una proprietà password, token o dati che non vorresti far leggere a un collega.

Quando usarlo

• Misurare cosa fanno i visitatori con le risposte: traccia su quali schede di riferimento

fanno clic, quali prodotti visualizzano, quali link seguono.

• Misurare le fasi di un funnel: invia eventi per ogni fase (ad es. Pricing.Viewed,

Signup.Started, Signup.Completed) e poi verifica quali sessioni includono quali fasi.

• Eseguire il debug delle interazioni dei template: attiva una traccia da un helper personalizzato e

controllala nella timeline della sessione per verificare che i collegamenti del tuo template funzionino come previsto.

Documenti correlati

• Helper
• Esaminare la timeline di una sessione
• Integrare un assistente in un sito web