Envoyer des événements personnalisés

Au-delà des événements intégrés que l’assistant enregistre automatiquement (débuts de session, requêtes, réactions, formulaires), vous pouvez envoyer vos propres événements personnalisés, chacun portant les propriétés que vous y attachez, depuis la page où l’assistant est intégré. Les événements personnalisés apparaissent dans le User Activity Feed et dans la chronologie de session à côté des événements standard : vous pouvez ainsi mettre en relation le comportement des visiteurs sur votre site avec la conversation de l’assistant et suivre précisément le contexte qui vous intéresse.

La méthode sendTrace

L’instance de l’assistant expose sendTrace :

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

Envoyer un événement avec des propriétés

C’est grâce aux propriétés que le suivi personnalisé devient utile : attachez le contexte que vous voulez suivre, sous forme de paires clé–valeur de type chaîne. Appelez sendTrace depuis n’importe quel script de la page où l’assistant est intégré : un gestionnaire de bouton, un changement de route, une étape de paiement :

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

Quelques points à connaître :

• Les valeurs sont des chaînes. Transmettez des chaînes et convertissez tout le reste :

String(count), price.toFixed(2). Les clés sont à votre choix.

• C’est un envoi sans attente de retour. L’appel renvoie une Promise, mais vous n’avez pas

besoin de l’await : si la connexion n’est pas prête, il échoue silencieusement au lieu de lever une erreur.

• Protégez les appels très précoces. Si une trace risque d’être envoyée avant que le

widget soit connecté, vérifiez d’abord isConnected :

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

Ce que deviennent vos propriétés

Une fois envoyé, un événement emporte ses propriétés partout où l’analytique peut les lire :

• User Activity Feed : vos propriétés s’affichent directement dans la colonne Details

de la ligne de l’événement (voir Suivre l’activité des utilisateurs).

• Chronologie de session : elles apparaissent dans la fiche de détail dépliable de

l’événement (voir Examiner la chronologie d’une session).

• Export CSV : l’export ActivityFeed les inclut, pour que vous puissiez les croiser

dans un tableur ou un outil de BI.

Votre eventName est stocké et affiché exactement tel que vous l’avez écrit (Pricing.Viewed), et chaque propriété définie est conservée telle quelle.

Noms de propriétés réservés

Seekdown attache automatiquement à chaque événement quelques propriétés d’identité et de routage. Vous ne les définissez pas, et elles n’apparaissent pas parmi vos Details personnalisés : elles alimentent à la place les colonnes User, Source et Time ainsi que le regroupement par session :

Évitez de réutiliser ces noms pour vos propres propriétés. Tout le reste est stocké tel quel et affiché dans Details.

Exemple : suivre les clics sur les références avec un helper personnalisé

La façon naturelle d’envoyer des événements personnalisés est de passer par un helper personnalisé : une petite fonction JavaScript que vous ajoutez dans l’éditeur avancé et que vous appelez depuis vos templates. La logique de suivi reste ainsi à côté du reste de la personnalisation de votre assistant.

1. Créez le helper. Dans l’éditeur avancé, ajoutez un nouveau helper nommé trackReferenceClick :

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

2. Appelez-le depuis un template. Surchargez le template highlighted (ou votre propre template de type de contenu) et branchez le helper sur le onclick du lien :

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

Chaque fois qu’un visiteur clique sur une fiche de référence, un événement Reference.Clicked est enregistré dans la chronologie de session avec l’ID et le titre de la référence.

3. Autre exemple : suivre la consultation d’un produit. Si votre assistant utilise un template personnalisé pour le type de contenu PRODUCT, ajoutez un helper nommé trackProductView :

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

Déclenchez-le ensuite lorsque la fiche produit s’affiche ou lorsque le visiteur clique dessus :

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

Fonctionnement

1. L’appel envoie l’événement au backend via la connexion SignalR de l’assistant : aucun

endpoint supplémentaire ni clé d’API n’est nécessaire.

1. Si vous définissez userInformation dans les options d’intégration,

ces propriétés sont automatiquement incluses dans l’événement (avec le préfixe user.) : vous n’avez donc pas besoin de les transmettre de nouveau.

1. L’événement est enregistré sous votre propre eventName, avec ses propriétés, et apparaît

à la fois dans la chronologie de session et dans le User Activity Feed.

Bonnes pratiques

• Nommez les événements Domaine.Action. Un schéma cohérent (Pricing.Viewed,

Signup.Started, Reference.Clicked) garde le flux lisible et regroupe les événements liés.

• Gardez des noms stables. Le flux et le CSV regroupent selon le nom exact de

l’événement : renommer un événement scinde son historique. Choisissez un nom et gardez-le.

• Envoyez des chaînes, et restez concis. Quelques propriétés courtes et significatives

valent mieux qu’un gros bloc ; convertissez nombres et booléens en chaînes.

• N’envoyez pas de secrets. Les traces sont stockées dans votre analytique et affichées

dans le tableau de bord : ne mettez jamais dans une propriété de mots de passe, de jetons ou de données que vous ne voudriez pas qu’un collègue lise.

Quand l’utiliser

• Mesurer ce que les visiteurs font des réponses : suivez les fiches de référence sur

lesquelles ils cliquent, les produits qu’ils consultent, les liens qu’ils suivent.

• Mesurer les étapes d’un entonnoir : envoyez des événements pour chaque étape (par ex.

Pricing.Viewed, Signup.Started, Signup.Completed) et voyez ensuite quelles sessions incluent quelles étapes.

• Déboguer les interactions des templates : déclenchez une trace depuis un helper

personnalisé et examinez-la dans la chronologie de session pour vérifier que le câblage de votre template fonctionne comme prévu.

Documentation associée

• Helpers
• Examiner la chronologie d’une session
• Intégrer un assistant sur un site web