Add opt-in persistent client IDs for stronger identification accuracy

[goldflag]

Sites can enable a localStorage-backed anonymous_id in place of the cookieless IP+UA fingerprint, trading it for a consent-banner obligation. Mutually exclusive with saltUserIds (opposite privacy postures); client-supplied anonymous_id is only trusted when the site opts in, closing a prior spoofable-identity gap. Session replay identity is threaded through the same client id so it stays in the same session lineage as pageview tracking.

Summary by CodeRabbit

• New Features
  • Added an optional persistent anonymous client ID setting for sites.
  • Persistent IDs can be used for tracking and session replay when enabled.
  • Added privacy settings controls with consent requirements.
• Bug Fixes
  • Prevented persistent client IDs and salted user IDs from being enabled together.
  • Client-provided identifiers are ignored unless the corresponding setting is enabled.
• Tests
  • Added coverage for identifier handling, fallback behavior, and conflicting privacy settings.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
rybbit	Ready	Preview, Comment	Jul 20, 2026 7:24am

[coderabbitai]

📝 Walkthrough

Walkthrough

Changes

The PR adds a persistentClientIds site setting, stores namespace-scoped identifiers in localStorage, propagates them through tracking and session replay payloads, and gates server-side identifier generation on the site setting. It also enforces mutual exclusion with saltUserIds.

Persistent Client ID Configuration and Identity Flow

Layer / File(s)	Summary
Site configuration and exclusivity enforcement server/drizzle/*, server/src/db/postgres/schema.ts, server/src/lib/siteConfig.ts, server/src/services/sites/*, server/src/api/sites/*, client/src/api/admin/endpoints/sites.ts, client/src/components/SiteSettings/GeneralTab.tsx, server/src/mcp/tools/sites.ts	The sites schema and configuration APIs support persistentClientIds; lifecycle validation rejects configurations where it and saltUserIds are both enabled, while the settings UI disables conflicting toggles.
Script persistence and payload propagation server/src/analytics-script/*, server/public/script*.js	The script creates or clears namespace-scoped local storage IDs and adds configured IDs to tracking and session replay payloads.
Tracking identity gating server/src/services/tracker/*	Client-supplied anonymous_id is used only when persistent IDs are enabled; otherwise identity generation falls back to IP and user-agent data.
Session replay identity ingestion server/src/types/sessionReplay.ts, server/src/api/sessionReplay/*, server/src/services/replay/*	Replay requests accept anonymousId, pass the site setting to ingestion, and use client-ID-based generation only for opted-in requests.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant SiteSettings
  participant SiteConfigAPI
  participant parseScriptConfig
  participant Tracker
  participant SessionReplayRecorder
  participant IdentityServices

  SiteSettings->>SiteConfigAPI: update persistentClientIds
  SiteConfigAPI->>parseScriptConfig: return persistentClientIds
  parseScriptConfig->>Tracker: provide persistentClientId
  parseScriptConfig->>SessionReplayRecorder: provide persistentClientId
  Tracker->>IdentityServices: submit anonymous_id
  SessionReplayRecorder->>IdentityServices: submit anonymousId
  IdentityServices->>IdentityServices: use client ID only when opted in

Loading

Possibly related PRs

• rybbit-io/rybbit#1048: Both changes modify session replay batch construction.
• rybbit-io/rybbit#1017: Both changes modify tracking identity construction in createBasePayload.
• rybbit-io/rybbit#597: Both changes modify parseScriptConfig tracking configuration handling.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 11.90% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change: adding opt-in persistent client IDs for stronger identification.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch persistent-client-ids

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}