/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", "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, 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) |

Consequences worth memorizing:

• **`surveyPopupDelaySeconds` is web-only.** If a mobile ticket blames the delay, it's a red herring.
• **URL targeting is effectively web-only.** Mobile SDKs decode the field but never enforce it; React Native filters those surveys out entirely. A mobile survey with a URL condition behaves as "no URL condition" (mobile/flutter) or "never shows" (RN).
• **Android ships no survey UI.** The app (or the Flutter plugin) must provide a `PostHogSurveysDelegate`. "Survey never renders on Android" is oft