# PostHog Session Replay — Watch Users Hit Your AI Features

> PostHog Session Replay records UI interactions, console logs, network requests. Watch what a user did before clicking your AI chat. PII auto-masked.

## Install

Copy the content below into your project:

## Quick Use

1. `posthog.init(...)` with `session_recording: { maskAllInputs: false }`
2. Add `class="pii"` to sensitive fields you want masked
3. PostHog dashboard → Session Replays — filter by event / user / device

---

## Intro

PostHog Session Replay records user interactions in your app — clicks, scrolls, console logs, network requests — playable as video. When a user reports 'the AI gave wrong answer', you replay their full session, see the prompt they typed, the model's reply, and what they did next. Best for: support and product teams debugging AI feature usability. Works with: web (JS SDK), iOS, Android, React Native. Setup time: 5 minutes.

---

### Enable session replay

```typescript
import posthog from "posthog-js";

posthog.init("phc_...", {
  api_host: "https://us.posthog.com",
  session_recording: {
    maskAllInputs: false,    // record what users type (mask in PII fields)
    maskTextSelector: ".pii", // anything with class="pii" is masked
    recordCrossOriginIframes: true,
    blockClass: "no-record",  // anything with class="no-record" is blocked
  },
});

posthog.identify("user_42", { plan: "pro" });
```

### Capture LLM-specific context

```typescript
// Annotate the recording with LLM events for richer playback timeline
posthog.capture("llm_call_started", {
  model: "claude-3-5-sonnet",
  prompt_length: 1234,
});

const response = await client.chat.completions.create(...);

posthog.capture("llm_call_completed", {
  model: "claude-3-5-sonnet",
  latency_ms: 1830,
  tokens: 450,
  user_satisfied: null,  // updated when user reacts
});
```

### Filter recordings by AI events

PostHog → Session Replays → Filter:
- Has event: `llm_call_completed` where `model = claude-3-5-sonnet`
- And: error occurred within 30s after
- And: user did NOT click positive feedback button

→ A queue of broken-experience replays for triage.

### Privacy-first defaults

- Password / credit-card / email fields auto-masked
- Custom mask via `maskTextSelector` / `data-private` attribute
- Block entire elements via `blockClass`
- Cookie banner consent integration (recordings only start after consent)

### What you'll catch

- Users abandoning your AI chat after 30s of typing
- Users reading the AI response then immediately searching elsewhere (signal: bad answer)
- Crashes on specific browsers/OSes
- Console errors that don't surface in your error tracker

---

### FAQ

**Q: Does session replay slow down my site?**
A: Negligible — recording happens in a Web Worker, payloads are gzipped and sent in batches. Typical overhead is <50ms on first paint and <2KB/min in network usage.

**Q: Can users opt out?**
A: Yes — call `posthog.opt_out_capturing()` from your settings page or after a cookie banner decline. PostHog also respects DNT headers when configured.

**Q: How long are recordings kept?**
A: Free tier 1 month, paid plans up to 1 year. Self-hosted is configurable. For long retention without cost, export recordings periodically via the API.

---

## Source & Thanks

> Built by [PostHog](https://github.com/PostHog). Licensed under MIT.
>
> [PostHog/posthog-js](https://github.com/PostHog/posthog-js) — ⭐ 1,500+

---

<!-- ZH -->

## 快速使用

1. `posthog.init(...)` 设 `session_recording: { maskAllInputs: false }`
2. 给敏感字段加 `class="pii"` 让它们被 mask
3. PostHog 仪表盘 → Session Replays，按事件 / 用户 / 设备过滤

---

## 简介

PostHog Session Replay 录用户在应用里的交互 —— 点击、滚动、console 日志、网络请求 —— 像视频一样回放。用户报「AI 给了错答案」时，你回放他完整会话、看他打的 prompt、模型回复、之后做了啥。适合调试 AI 功能可用性的支持和产品团队。兼容 web（JS SDK）、iOS、Android、React Native。装机时间 5 分钟。

---

### 启用 session replay

```typescript
import posthog from "posthog-js";

posthog.init("phc_...", {
  api_host: "https://us.posthog.com",
  session_recording: {
    maskAllInputs: false,    // 录用户打的字（PII 字段单独 mask）
    maskTextSelector: ".pii", // class="pii" 的元素被 mask
    recordCrossOriginIframes: true,
    blockClass: "no-record",  // class="no-record" 的元素被屏蔽
  },
});

posthog.identify("user_42", { plan: "pro" });
```

### 捕获 LLM 专属上下文

```typescript
// 给录像时间线加 LLM 事件标记，回放更丰富
posthog.capture("llm_call_started", {
  model: "claude-3-5-sonnet",
  prompt_length: 1234,
});

const response = await client.chat.completions.create(...);

posthog.capture("llm_call_completed", {
  model: "claude-3-5-sonnet",
  latency_ms: 1830,
  tokens: 450,
  user_satisfied: null,  // 用户反应后更新
});
```

### 按 AI 事件过滤录像

PostHog → Session Replays → 过滤：
- 含事件：`llm_call_completed`（`model = claude-3-5-sonnet`）
- 并且：30 秒内发生错误
- 并且：用户*没*点正面反馈按钮

→ 一队坏体验录像供分诊。

### 隐私优先默认

- 密码 / 信用卡 / 邮箱字段自动 mask
- 用 `maskTextSelector` / `data-private` 属性自定义 mask
- 用 `blockClass` 屏蔽整个元素
- Cookie banner 同意集成（同意后才开始录）

### 你会发现的

- 用户打字 30 秒后放弃 AI chat
- 用户读完 AI 响应立刻去别处搜（信号：答案不好）
- 特定浏览器/OS 上的崩溃
- 错误追踪器里看不到的 console 错误

---

### FAQ

**Q: Session replay 会拖慢站点吗？**
A: 可忽略 —— 录制在 Web Worker 里，payload gzip 压缩批量发。典型首屏开销 <50ms，网络 <2KB/分钟。

**Q: 用户能选择不被录吗？**
A: 能 —— 在设置页或 cookie banner 拒绝后调 `posthog.opt_out_capturing()`。配置后也尊重 DNT header。

**Q: 录像保留多久？**
A: 免费档 1 个月，付费档最多 1 年。自托管可配。要长保留又免费就定期通过 API 导出录像。

---

## 来源与感谢

> Built by [PostHog](https://github.com/PostHog). Licensed under MIT.
>
> [PostHog/posthog-js](https://github.com/PostHog/posthog-js) — ⭐ 1,500+


---
Source: https://tokrepo.com/en/workflows/posthog-session-replay-watch-users-hit-your-ai-features
Author: PostHog