/debugging-surveys

name: debugging-surveys
description: >-
  Debug, support, and build PostHog Surveys across the backend and all five SDKs
  (web/posthog-js, iOS, Android, Flutter, React Native). Use whenever a Surveys
  support ticket is pasted ("survey not showing", "fewer responses than expected",
  "responses disappeared", "responses are incomplete", "only the first question was
  answered", "the user says they didn't mean to submit", "survey shows on wrong platform"),
  when diagnosing why a survey does or doesn't display, or when doing survey feature work
  that must ship across SDKs. Covers the eligibility pipeline, how a response actually gets
  stored (partial responses, branching, optional questions, auto-submit), cross-SDK feature
  parity, the known-cause catalog, read-only diagnostic queries, staff access, and the
  customer-reply style guide.

Debugging surveys

PostHog Surveys is a no-code in-app form builder. A customer creates a survey in the PostHog UI; it must then be evaluated and rendered by whichever SDK their app runs. **Most "survey not showing" tickets are eligibility problems, not rendering bugs** — the SDK correctly decided the user is not eligible, and the job is to find _which_ gate failed and _why_.

Repos

GitHub is the source of truth for where the code lives. When you need to read or change SDK source, resolve a local checkout via the registry described in [references/local-repos.md](references/local-repos.md) so a clone is found once and reused — don't re-clone every session. First time on a machine, run `python3 scripts/repos.py init` to auto-discover existing checkouts; thereafter `python3 scripts/repos.py ensure <repo>` prints the path (and `--clone` clones if missing).

| Concern | Repo | Where to look | | -------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------ | | Product UI + backend | this monorepo (PostHog/posthog) | UI: `frontend/src/scenes/surveys/`, backend: `products/surveys/backend/` | | Web SDK | [PostHog/posthog-js](https://github.com/PostHog/posthog-js) | `packages/browser/` | | React Native SDK | [PostHog/posthog-js](https://github.com/PostHog/posthog-js) (same monorepo) | `packages/react-native/` | | iOS SDK | [PostHog/posthog-ios](https://github.com/PostHog/posthog-ios) | survey rendering + eligibility | | Android SDK | [PostHog/posthog-android](https://github.com/PostHog/posthog-android) | eligibility (delegate-based UI) | | Flutter SDK | [PostHog/posthog-flutter](https://github.com/PostHog/posthog-flutter) | Dart rendering; native iOS/Android handles eligibility | | Public docs | [PostHog/posthog.com](https://github.com/PostHog/posthog.com) | `contents/docs/surveys/` |

Always check the local checkout is present and on a sane branch before quoting code; line numbers drift, so grep for the symbol rather than trusting a remembered line number.

Cross-SDK feature parity (check this FIRST)

A large class of tickets is "customer expects a feature their platform doesn't support." Confirm the survey's `lib` / the customer's platform before anything else, then consult this table. Verified against the SDK source — re-verify if it's been months, the gaps get filled over time.

| Feature | Web (posthog-js) | iOS | Android | Flutter | React Native | | -------------------------------- | ------------------------------- | ----------------------------------------- | ---------------------------------- | ---------------------------------- | --------------------------------------- | | Rendering | DOM + shadow root | Native SwiftUI (`SurveysWindow`) | **No built-in UI** — delegate only | Dart widgets (`SurveyBottomSheet`) | RN components (`SurveyModal`) | | Event-based triggers | yes (since 1.137.0, 2024-06-05) | yes | yes | yes (native side) | yes | | URL / screen targeting | yes | decoded but **NOT evaluated** (`// TODO`) | decoded but **NOT evaluated** | **NOT evaluated** (native gap) | **explicitly excluded** in filter | | Feature-flag / cohort targeting | yes | yes | yes | yes (native side) | yes | | `seenSurveyWaitPeriodInDays` | yes | yes | yes | yes (native side) | stored but **comparison commented out** | | `surveyPopupDelaySeconds` | yes | **not implemented** | **not implemented** | **not implemented** | **not implemented** (TODO) | | `enable_partial_responses` | yes (≥ 1.240.0) | **no** | **no** | **no** | **no** | | `skipSubmitButton` (auto-submit) | yes (≥ 1.244.0) | **no*