Visites guidées produit

Les visites guidées (tours) sont des parcours pas à pas que le SDK Kilden rend sur vos propres pages : chaque étape est une carte qui pointe vers un élément de votre page (tooltip + spotlight) ou, sans ancre, s’affiche comme une modale centrée. Ce sont un type d’unité in-app : le ciblage, la planification et les règles d’affichage fonctionnent comme pour les bannières et les enquêtes — le serveur décide qui voit une visite, le SDK décide où et quand.

Une visite ne casse jamais votre page : un sélecteur qui ne correspond à rien fait simplement sauter l’étape, et chaque listener est nettoyé quand la visite se termine.

Construire une visite

Dans le panel, allez dans In-app → New unit → Tour. Chaque étape comporte :

Champ	Ce qu’il fait
Texte	Ce que dit l’étape (plus un titre et une image optionnels)
Ancre	Un sélecteur CSS de l’élément visé par l’étape. Vide = modale centrée
Position	De quel côté de l’ancre la carte apparaît (top, bottom, left, right, ou centrée)
Avancement	Bouton Next (par défaut), ou avancer quand le visiteur clique sur l’élément ancré lui-même

Les étapes avancent dans l’ordre ; les visiteurs peuvent revenir en arrière, et un contrôle Skip s’affiche sauf si vous le désactivez. Les visites utilisent par défaut la fréquence once : un visiteur qui a terminé (ou passé) une visite ne la revoit pas.

Ancrer les étapes : le sélecteur d’éléments

Pas besoin d’écrire les sélecteurs à la main. À côté du champ d’ancre de chaque étape, Pick on your site ouvre votre page dans un nouvel onglet avec la barre du picker Kilden active — cliquez sur l’élément voulu et le sélecteur revient dans l’éditeur.

Le picker synthétise le sélecteur le plus stable possible, en préférant (dans l’ordre) :

1. Un id stable
2. Un attribut data-* — avec data-kilden-tour au-dessus de tous
3. Des attributs sémantiques (aria-label, name, role, href)
4. Le texte visible de l’élément
5. La position structurelle (chaînes nth-child)

Les classes utilitaires CSS (Tailwind et consorts) ne sont jamais utilisées : elles changent à chaque refonte. Les niveaux 4 et 5 sont marqués faibles — ils fonctionnent, mais dépendent de textes ou d’une mise en page qui peuvent changer.

Le picker est réservé aux auteurs : la barre s’active via un ticket éphémère signé par le panel et vérifié côté serveur avant de se monter. Les visiteurs ne la voient ni ne la téléchargent jamais.

data-kilden-tour : l’ancre permanente

L’ancre la plus fiable est celle qui existe pour la visite. Ajoutez un attribut data-kilden-tour aux éléments que vous visez :

<button data-kilden-tour="take-a-number">Take a number</button>

L’ancre de l’étape devient alors [data-kilden-tour="take-a-number"] — insensible aux refontes, aux changements de texte et aux réorganisations du DOM. Quand le picker ne trouve qu’une ancre faible, il suggère l’attribut exact à ajouter. Si vous pouvez modifier votre markup, faites-le : c’est un attribut, et l’ancre ne casse jamais.

Ancres par texte

Quand la meilleure ancre disponible est le texte visible de l’élément, le picker émet l’extension :kilden-text("…") de Kilden sur une base CSS :

button:kilden-text("Take a number")

Le SDK résout le sélecteur de base et filtre par le texte propre de l’élément (sans espaces superflus). Attention : cela casse dès que le texte change (traductions comprises) — préférez data-kilden-tour quand c’est possible.

Prévisualiser une visite

Itérer sur une visite active était pénible : une vraie visite la marque comme vue et elle ne s’affiche plus. Preview on my site (sous l’aperçu de l’éditeur) résout cela :

• Votre page s’ouvre avec la visite rendue exactement comme éditée à l’instant — même les changements non enregistrés.
• Rien n’est marqué comme vu, aucun événement d’analytics n’est enregistré, et les règles de fréquence/URL sont ignorées : prévisualiser signifie « montre-la-moi maintenant ».
• Une barre flottante Kilden preview offre Replay, pour regarder la visite autant de fois que nécessaire.
• La prévisualisation démarre à l’étape que vous éditiez, pas à la première.
• Ce que le SDK aurait suivi est reflété dans la console du navigateur ([kilden] preview (not tracked): …).

Comme le picker, la prévisualisation est autorisée par un ticket signé éphémère — un visiteur ne peut pas la déclencher en modifiant l’URL.

Ancres cassées

Si votre page change et que le sélecteur d’une étape ne correspond plus, la visite dégrade proprement : l’étape attend jusqu’à 3 secondes (pour les SPA au rendu tardif), puis est sautée. Les visiteurs ne restent jamais bloqués — mais l’étape disparaît en silence.

Le panel surveille cela. La portée de chaque étape ancrée est mesurée ($tour_step_viewed par étape), et quand une étape affiche une portée nulle alors que la visite continue de démarrer, l’éditeur la signale avec Anchor may be broken — en distinguant « n’a jamais correspondu » de « a cessé de correspondre récemment » (la signature d’un déploiement qui a renommé l’élément). Re-choisissez l’élément ou, mieux, donnez-lui un attribut data-kilden-tour.

Mesurer

Les visites émettent des événements $ interrogeables comme n’importe quelle donnée :

Événement	Quand
$tour_started	La première étape s’est affichée
$tour_step_viewed	Une étape s’est affichée ($step_index, $step_id)
$tour_completed	Le visiteur est arrivé au bout
$tour_dismissed	Le visiteur a passé

La page de détail de l’unité montre un entonnoir d’abandon par étape (personnes uniques par étape, indexé par l’id immuable de l’étape).