Tours de produto

Tours são passo a passo que o SDK da Kilden renderiza sobre as suas próprias páginas: cada etapa é um cartão que aponta para um elemento da sua página (tooltip + spotlight) ou, sem âncora, aparece como um modal centralizado. São um tipo de unit in-app, então o targeting, o agendamento e as regras de exibição funcionam igual a banners e surveys — o servidor decide quem vê um tour, o SDK decide onde e quando.

Um tour nunca quebra a sua página: um seletor que não corresponde a nada simplesmente pula aquela etapa, e todos os listeners são limpos quando o tour termina.

Construindo um tour

No painel, vá em In-app → New unit → Tour. Cada etapa tem:

Campo	O que faz
Texto	O que a etapa diz (mais um título e imagem opcionais)
Âncora	Um seletor CSS do elemento para o qual a etapa aponta. Vazio = modal centralizado
Posição	De que lado da âncora o cartão aparece (top, bottom, left, right, ou centralizado)
Avanço	Botão Next (padrão), ou avançar quando o visitante clica no próprio elemento ancorado

As etapas avançam em ordem; os visitantes podem voltar, e um controle Skip é mostrado a menos que você o desative. Tours usam por padrão frequência once: um visitante que terminou (ou pulou) um tour não o vê de novo.

Ancorando etapas: o seletor de elementos

Você não precisa escrever seletores à mão. Ao lado do campo de âncora de cada etapa, Pick on your site abre a sua página em uma nova aba com a barra do picker da Kilden ativa — clique no elemento que você quer e o seletor volta para o editor.

O picker sintetiza o seletor mais estável que encontra, preferindo (nesta ordem):

1. Um id estável
2. Um atributo data-* — com data-kilden-tour acima de todos
3. Atributos semânticos (aria-label, name, role, href)
4. O texto visível do elemento
5. Posição estrutural (cadeias nth-child)

Classes utilitárias de CSS (Tailwind e afins) nunca são usadas: mudam a cada redesign. Os níveis 4 e 5 são marcados como fracos — funcionam, mas dependem de textos ou layout que podem mudar.

Escolher elementos é só para autores: a barra é ativada por um ticket de curta duração assinado pelo painel e verificado server-side antes de montar. Visitantes nunca a veem nem a baixam.

data-kilden-tour: a âncora permanente

A âncora mais confiável é uma que existe para o tour. Adicione um atributo data-kilden-tour aos elementos para os quais você aponta:

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

A âncora da etapa fica então [data-kilden-tour="take-a-number"] — imune a redesigns, mudanças de texto e reorganizações do DOM. Quando o picker só encontra uma âncora fraca, ele sugere o atributo exato a adicionar. Se você pode editar seu markup, faça isso: é um atributo e a âncora nunca quebra.

Âncoras por texto

Quando a melhor âncora disponível é o texto visível do elemento, o picker emite a extensão :kilden-text("…") da Kilden sobre uma base CSS:

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

O SDK resolve o seletor base e filtra pelo texto próprio do elemento (aparado). Atenção: isso quebra no momento em que o texto muda (traduções incluídas) — prefira data-kilden-tour quando puder.

Pré-visualizando um tour

Iterar em um tour ativo era doloroso: uma visita real o marca como visto e ele não aparece mais. Preview on my site (abaixo da pré-visualização do editor) resolve isso:

• Sua página abre com o tour renderizado exatamente como está editado agora — até mudanças não salvas.
• Nada é marcado como visto, nenhum evento de analytics é registrado, e as regras de frequência/URL são ignoradas: preview significa «me mostre agora».
• Uma barra flutuante Kilden preview oferece Replay, para você assistir ao tour quantas vezes precisar.
• A pré-visualização começa na etapa que você estava editando, não na etapa um.
• O que o SDK teria rastreado é espelhado no console do navegador ([kilden] preview (not tracked): …).

Como o picker, a pré-visualização é autorizada por um ticket assinado de curta duração — um visitante não consegue ativá-la editando a URL.

Âncoras quebradas

Se a sua página muda e o seletor de uma etapa deixa de corresponder, o tour degrada com graça: a etapa espera até 3 segundos (para SPAs que renderizam tarde) e depois é pulada. Visitantes nunca ficam presos — mas a etapa desaparece em silêncio.

O painel vigia isso. O alcance de cada etapa ancorada é medido ($tour_step_viewed por etapa), e quando uma etapa mostra alcance zero enquanto o tour continua começando, o editor a marca com Anchor may be broken — distinguindo «nunca correspondeu» de «parou de corresponder recentemente» (a assinatura de um deploy que renomeou o elemento). Escolha o elemento novamente ou, melhor, dê a ele um atributo data-kilden-tour.

Medindo

Tours emitem eventos $ que você pode consultar como qualquer outro dado:

Evento	Quando
$tour_started	A primeira etapa foi renderizada
$tour_step_viewed	Uma etapa foi renderizada ($step_index, $step_id)
$tour_completed	O visitante chegou ao fim
$tour_dismissed	O visitante pulou

A página de detalhe da unit mostra um funil de drop-off por etapa (pessoas únicas por etapa, chaveado pelo id imutável da etapa).