Demonstração de replay de sessão

O aplicativo de demonstração de replay de sessão é um explorador de documentação desenvolvido com JavaScript puro. Ele demonstra como a instrumentação mínima de replay de sessão pode ser enxuta — uma tag de script e uma chamada de inicialização capturam automaticamente todas as interações do usuário.

O repositório inclui duas branches:

• main — totalmente instrumentada e pronta para uso imediato
• pre-instrumented — uma versão limpa, sem instrumentação, com comentários no código indicando onde adicioná-la

Este guia usa primeiro a branch main para mostrar o replay de sessão em ação e, em seguida, apresenta o código de instrumentação para que você possa aplicar o mesmo padrão ao seu próprio aplicativo.

Para saber mais sobre o que é replay de sessão e como ele se encaixa no ClickStack, consulte a página do recurso replay de sessão.

• Docker e Docker Compose instalados
• Portas 3000, 4317, 4318 e 8080 disponíveis

Clone o repositório

git clone https://github.com/ClickHouse/clickstack-session-replay-demo
cd clickstack-session-replay-demo

Inicie o ClickStack

docker-compose up -d clickstack

Obtenha sua API key

1. Abra o HyperDX em http://localhost:8080
2. Crie uma conta ou faça login, se necessário
3. Acesse Team Settings → API Keys
4. Copie sua API key de ingestão

5. Defina-a como uma variável de ambiente:

export CLICKSTACK_API_KEY='your-api-key-here'

Inicie o aplicativo de demonstração

docker-compose --profile demo up demo-app

Abra http://localhost:3000 no navegador e interaja com o app — pesquise tópicos, filtre por categoria, veja exemplos de código e favorite itens.

Todas as interações são capturadas automaticamente pelo SDK do navegador do ClickStack.

Veja o replay da sua sessão

Volte ao HyperDX em http://localhost:8080 e acesse Client Sessions na barra lateral esquerda.

Você deverá ver sua sessão listada com a duração e a contagem de eventos. Clique no botão ▶️ para reproduzi-la.

Alterne entre os modos Highlighted e All Events para ajustar o nível de detalhe na linha do tempo.

O aplicativo de demonstração mostra como é possível habilitar o replay de sessão com pouquíssimo código. Bastam duas adições ao aplicativo:

1. Inclua o SDK (app/public/index.html):

<script src="https://unpkg.com/@hyperdx/browser@0.21.0/build/index.js"></script>

2. Inicialize o ClickStack (app/public/js/app.js):

window.HyperDX.init({
  url: 'http://localhost:4318',
  apiKey: window.CLICKSTACK_API_KEY,
  service: 'clickhouse-session-replay-demo',
  consoleCapture: true,
  advancedNetworkCapture: true,
});

Todo o restante é código padrão da aplicação. O SDK captura automaticamente todas as interações do usuário, os logs do console, as requisições de rede e os erros — nenhuma instrumentação adicional é necessária.

Para instrumentar o app do zero, mude para a branch pre-instrumented:

git checkout pre-instrumented

Esta branch contém a mesma aplicação, sem nenhuma instrumentação do ClickStack. Os comentários no código em app/public/index.html e app/public/js/app.js indicam exatamente onde adicionar os dois trechos de código acima. Depois de adicioná-los, reinicie a aplicação de demonstração, e suas interações começarão a aparecer no ClickStack.

1. Verifique se há erros no console do navegador
2. Verifique se o ClickStack está em execução: docker-compose ps
3. Confirme se a API key está definida: echo $CLICKSTACK_API_KEY
4. Ajuste o intervalo de tempo na visualização Client Sessions (tente Últimos 15 minutos)
5. Faça uma recarga forçada do navegador: Cmd+Shift+R (Mac) ou Ctrl+Shift+R (Windows/Linux)

A chave de API não foi definida corretamente. Certifique-se de que você:

1. A exportou no terminal: export CLICKSTACK_API_KEY='your-key'
2. Iniciou o aplicativo de demonstração no mesmo terminal em que a exportou
3. Obteve a chave na UI do HyperDX (e não uma string gerada aleatoriamente)

Pare os serviços:

docker-compose down

Remova todos os dados:

docker-compose down -v

• replay de sessão — visão geral da funcionalidade, opções de SDK e controles de privacidade
• Referência do SDK do navegador — todas as opções do SDK e configuração avançada
• Primeiros passos do ClickStack — implante o ClickStack e faça a ingestão dos seus primeiros dados
• Todos os datasets de exemplo — outros datasets de exemplo e guias