메인 콘텐츠로 건너뛰기
요약이 가이드는 ClickStack Browser SDK를 사용하여 웹 애플리케이션에 세션 리플레이 계측을 적용하는 방법을 안내합니다. 미리 생성된 데이터를 불러오는 다른 샘플 데이터셋과 달리, 이 데모는 직접 상호작용하면서 세션 데이터를 생성할 수 있는 대화형 애플리케이션을 제공합니다.소요 시간: 10~15분

​
개요

세션 리플레이 데모 애플리케이션은 바닐라 JavaScript로 구축한 문서 탐색기입니다. 이 애플리케이션은 세션 리플레이를 얼마나 간단하게 계측할 수 있는지 보여줍니다. 즉, script 태그 하나와 초기화 호출 한 번만으로 모든 사용자 상호작용을 자동으로 수집합니다. 이 리포지토리에는 2개의 브랜치가 포함되어 있습니다:
  • main — 계측이 모두 적용되어 있어 즉시 사용할 수 있습니다
  • pre-instrumented — 계측이 없는 깔끔한 버전으로, 어디에 추가해야 하는지 보여주는 코드 주석이 포함되어 있습니다
이 가이드에서는 먼저 main 브랜치를 사용해 세션 리플레이가 실제로 동작하는 모습을 확인한 다음, 동일한 패턴을 자체 애플리케이션에 적용할 수 있도록 계측 코드를 단계별로 설명합니다. 세션 리플레이가 무엇이며 ClickStack에서 어떤 역할을 하는지에 대한 배경 설명은 Session Replay 기능 페이지를 참조하십시오.

​
사전 요구사항

  • Docker 및 Docker Compose가 설치되어 있어야 합니다
  • 포트 3000, 4317, 4318, 8080을 사용할 수 있어야 합니다

​
데모 실행하기

1

​
리포지토리 복제하기

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

​
ClickStack 시작하기

docker-compose up -d clickstack
3

​
API Key 가져오기

  1. http://localhost:8080에서 HyperDX를 여십시오
  2. 필요한 경우 계정을 만들거나 로그인하십시오
  3. Team Settings → API Keys로 이동하십시오
  4. 수집 API Key를 복사하십시오
  1. 이를 환경 변수로 설정하십시오:
export CLICKSTACK_API_KEY='your-api-key-here'
4

​
데모 애플리케이션 시작하기

docker-compose --profile demo up demo-app
CLICKSTACK_API_KEY 변수를 export한 동일한 터미널에서 이 명령을 실행해야 합니다.
브라우저에서 http://localhost:3000을 열고 앱을 사용해 보십시오. 주제를 검색하고, 카테고리별로 필터링하고, 코드 예시를 보고, 항목을 북마크할 수 있습니다.모든 상호작용은 ClickStack Browser SDK에 의해 자동으로 기록됩니다.
5

​
세션 리플레이 보기

http://localhost:8080의 HyperDX로 돌아가 왼쪽 사이드바에서 Client Sessions로 이동하십시오.지속 시간과 이벤트 수가 표시된 세션이 목록에 나타나야 합니다. ▶️ 버튼을 클릭해 재생하십시오.타임라인의 상세 수준을 조정하려면 Highlighted 모드와 All Events 모드 사이를 전환하십시오.

​
계측

데모 애플리케이션은 세션 리플레이를 활성화하는 데 필요한 코드가 얼마나 적은지 보여줍니다. 애플리케이션에 두 가지만 추가하면 됩니다. 1. SDK를 포함합니다 (app/public/index.html): 
<script src="https://unpkg.com/@hyperdx/browser@0.21.0/build/index.js"></script>
2. 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,
});
그 밖의 모든 부분은 일반적인 애플리케이션 코드입니다. SDK가 모든 사용자 상호작용, 콘솔 로그, 네트워크 요청, 오류를 자동으로 수집하므로 별도의 계측 작업은 필요하지 않습니다.

​
직접 해보기

앱에 처음부터 텔레메트리 수집을 추가해 보려면 pre-instrumented 브랜치로 전환하세요: 
git checkout pre-instrumented
이 브랜치에는 ClickStack 계측이 적용되지 않은 동일한 애플리케이션이 들어 있습니다. app/public/index.html 및 app/public/js/app.js의 코드 주석에 위의 두 코드 조각을 정확히 어디에 추가해야 하는지가 표시되어 있습니다. 추가한 후 데모 앱을 다시 시작하면 수행한 상호작용이 ClickStack에 표시되기 시작합니다.

​
문제 해결

​
HyperDX에 세션이 표시되지 않는 경우

  1. 브라우저 콘솔에서 오류를 확인합니다
  2. ClickStack이 실행 중인지 확인합니다: docker-compose ps
  3. API Key가 설정되어 있는지 확인합니다: echo $CLICKSTACK_API_KEY
  4. Client Sessions 뷰에서 시간 범위를 조정합니다(최근 15분으로 설정해 보십시오)
  5. 브라우저에서 강력 새로고침을 수행합니다: Cmd+Shift+R (Mac) 또는 Ctrl+Shift+R (Windows/Linux)

​
401 인증되지 않음 오류

API Key가 올바르게 설정되지 않았습니다. 다음 사항을 확인하세요:
  1. 터미널에서 export CLICKSTACK_API_KEY='your-key'로 내보냈는지
  2. 내보낸 동일한 터미널에서 데모 앱을 시작했는지
  3. 키를 HyperDX UI에서 가져왔는지(무작위로 생성한 문자열이 아님)

​
정리

서비스를 중지하세요: 
docker-compose down
모든 데이터 제거: 
docker-compose down -v

​
더 알아보기

마지막 수정일 2026년 6월 10일