会话回放演示

会话回放演示应用是一个使用原生 JavaScript 构建的文档浏览器。它展示了会话回放的埋点可以做到多么精简——只需一个 script 标签和一次初始化调用，就能自动捕获所有用户交互。

该仓库包含两个分支：

• main — 已完成全部埋点，可直接使用
• pre-instrumented — 未埋点的纯净版本，代码注释中标明了应在何处添加埋点

本指南会先使用 main 分支，查看会话回放的实际效果；然后再逐步讲解埋点代码，以便你将同样的模式应用到自己的应用中。

有关会话回放的背景及其在 ClickStack 中的作用，请参阅会话回放功能页面。

• 已安装 Docker 和 Docker Compose
• 3000、4317、4318 和 8080 端口可用

克隆代码仓库

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

启动 ClickStack

docker-compose up -d clickstack

获取 API key

1. 在 http://localhost:8080 打开 HyperDX
2. 创建账号，或根据需要登录
3. 前往 Team Settings → API Keys
4. 复制你的 摄取 API key

5. 将其设置为环境变量：

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

启动演示应用

docker-compose --profile demo up demo-app

在浏览器中打开 http://localhost:3000 并与应用交互——搜索主题、按类别过滤、查看代码示例，以及收藏条目。

所有交互都会由 ClickStack Browser SDK 自动记录。

查看你的会话回放

返回 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 中。

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)

API key 设置不正确。请确保你已：

1. 在终端中导出该密钥：export CLICKSTACK_API_KEY='your-key'
2. 在导出该密钥的同一个终端中启动演示应用
3. 该密钥是从 HyperDX 界面获取的 (而不是随意生成的一串字符串)

停止服务：

docker-compose down

删除所有数据：

docker-compose down -v

• 会话回放 — 功能概览、SDK 选项和隐私控制
• Browser SDK 参考文档 — 完整的 SDK 选项及高级配置
• ClickStack 快速开始 — 部署 ClickStack 并摄取您的第一批数据
• 所有示例数据集 — 其他示例数据集和相关指南