Skip to content
Agent Analytics

Session replay

Session replay helps explain why a measured session behaved the way it did. Agent Analytics records structured DOM and interaction events with rrweb; it does not record a literal screen video.

Replay is a Pro and complimentary-account feature. It is disabled by default and requires both server-side project enablement and a separate replay.js installation. The normal tracker.js never starts or loads replay.

Enable one project

Section titled “Enable one project”

First confirm that the project has its real production HTTPS origin in allowed_origins. Then inspect and enable replay:

Terminal window
npx --yes @agent-analytics/[email protected] replays settings my-site
npx --yes @agent-analytics/[email protected] replays enable my-site \
  --recording-start after_consent \
  --mask '.customer-id,.billing-address' \
  --block '.payment-form'

Enabling the setting only makes the project eligible. Add the separate bootstrap after the normal tracker, using the same project token:

<script src="https://api.agentanalytics.sh/tracker.js"
  data-project="my-site"
  data-token="aat_PROJECT_TOKEN"></script>
<script src="https://api.agentanalytics.sh/replay.js"
  data-token="aat_PROJECT_TOKEN"></script>

For after_consent, call window.aaReplay.consent() only after the visitor grants the relevant consent. Call window.aaReplay.revoke() when consent is withdrawn. You can inspect fail-closed startup state with window.aaReplay.status() and window.aaReplay.reason().

Your Content Security Policy must allow:

  • https://api.agentanalytics.sh in script-src and connect-src
  • your account R2 S3 endpoint, https://<CLOUDFLARE_ACCOUNT_ID>.r2.cloudflarestorage.com, in connect-src
  • blob: in worker-src

If the required browser features or CSP permissions are unavailable, replay stays off rather than processing the payload on the main thread.

Find and watch a replay

Section titled “Find and watch a replay”

Start from analytics, then move to the replay only when it can answer a qualitative question:

Terminal window
npx --yes @agent-analytics/[email protected] sessions my-site
npx --yes @agent-analytics/[email protected] replays list my-site --session sess_EXAMPLE
npx --yes @agent-analytics/[email protected] replays open --session sess_EXAMPLE --project my-site

sessions shows a ▶ replay marker and an exact open command when the signed-in caller has replay access and a linked replay exists. One analytics session can have multiple replay segments; opening by session selects the newest playable segment and tells you when more segments exist.

The command returns a short-lived viewer link. Open it on desktop or phone. The player fits desktop recordings to a smaller screen, supports zoom and pan, marks interaction activity on the timeline, and skips long inactive periods. Its language picker supports English, Hebrew, and Simplified Chinese and follows the language selected in the account app. Its Details panel includes safe linked-session context such as event sequence, device, country, referrer, and attribution when those fields exist.

Viewer links expire after one hour. Run the open command again whenever you need a fresh link. Treat the URL as a bearer credential during that hour: do not log, persist, or publish it. The viewer remains replay-specific and sandboxed, blocking recorded scripts, external network requests, forms, navigation, and popups.

Replay is supporting evidence, not aggregate proof. Use funnels, paths, retention, events, and session lists to establish the pattern; use selected replays to understand friction and form a testable explanation.

Privacy and limits

Section titled “Privacy and limits”

Mandatory controls cannot be disabled. Replay masks form and contenteditable values, redacts recognizable PII before upload, removes URL query strings and fragments, and honors data-aa-mask, data-aa-block, and data-aa-ignore. Add project selectors for product-specific sensitive areas.

Each replay is limited to 15 minutes and 2 MiB compressed. Accounts retain at most 300 MiB, rotate down to 270 MiB when necessary, and have a 1.5 GiB rolling 30-day ingestion limit. App-driven retention is 30 days.

Recordings need an initial full snapshot and at least one second of replay event timeline to be retained. Shorter captures are discarded, and any already-uploaded replay objects are deleted automatically.

Manage stored replay data from the CLI:

Terminal window
npx --yes @agent-analytics/[email protected] replays list my-site
npx --yes @agent-analytics/[email protected] replays get rpl_EXAMPLE
npx --yes @agent-analytics/[email protected] replays usage
npx --yes @agent-analytics/[email protected] replays delete rpl_EXAMPLE
npx --yes @agent-analytics/[email protected] replays disable my-site

Disabling replay immediately stops new recording starts and upload authorizations. It does not delete existing retained recordings; delete them separately when needed.