[posthog]

Why

Every surveys-capable SDK honors appearance.surveyPopupDelaySeconds, but the surveys spec never mentions it. The spec's nearby rules ("allow only one active prompt", "a survey should be marked active before its shown/response/closed callbacks can mutate response state") are written for a survey that is already on screen, so the window between deciding to show a survey and the survey appearing was unspecified — and SDKs diverged there.

What changed in the SDKs

• posthog-android#849 — Android marked a survey active only once it was shown, so nothing was reserved while the delay ran: each repeat trigger event re-rendered the survey and restarted the delegate's timer, and trigger events firing faster than the delay kept the survey from showing at all. It now reserves the survey (pendingPresentation) before renderSurvey, matching iOS (scheduleSurveyDisplay sets pendingSurvey before the delay) and the browser (_addSurveyToFocus before the timer in handlePopoverSurvey). The delegate contract now requires reporting back, because a silently dropped survey would hold the reservation.
• posthog-flutter#627 — plumbs the delay into its own bottom sheet and had to rediscover the same rules from the native code: zero, negative, or missing values show immediately, and a survey dropped during the wait is not marked seen or dismissed.

What this PR does

Adds a Survey popup delay requirement to openspec/specs/surveys/spec.md (proposed, applied, and archived on this branch per the repo workflow):

• A positive delay waits before display; missing, zero, or negative shows immediately, and a negative value never means "never show".
• The survey is reserved as the pending prompt before the wait, so a repeat trigger or another eligibility pass neither restarts the wait nor shows a second copy — the wait is measured from the first trigger.
• A survey that never reached the screen is not seen and emits no survey shown / survey dismissed; the reservation is released when it is shown, dropped, or on reset.
• A delegating host UI layer must report back (shown or closed), since the reservation gates every later survey.
• The browser-only refinements (resume from the trigger's activation timestamp; an explicit display call bypassing the delay) are recorded as allowed, not required.

Uncertain / worth a look

• Eligibility re-check on elapse is stated as SHOULD, not SHALL. The browser re-checks the full display predicate when the timer fires; the native SDKs do not. Writing it as SHALL would make iOS and Android non-conforming today, so I kept it weaker — tighten it if that's the intended contract.
• posthog-react-native reads surveyPopupDelaySeconds in its survey provider, but I did not verify whether it reserves the survey before the wait. The Impact section says so rather than claiming conformance.

---

Created with PostHog Desktop

🤖 Generated with Claude Code

[marandaneto]

Automated advisory code review.

[marandaneto]

blocking: Qualify iOS conformance for a close before first display — The blanket iOS conformance claim misses a valid pre-show delegate-close path: the integration reserves activeSurvey before calling the delegate, but handleSurveyClosed marks that still-current presentation seen and emits survey dismissed even when its delegate never called onSurveyShown. That contradicts this PR’s new no-seen/no-dismissal requirement and its instruction that an unable-to-display host report closed; normal teardown avoids the problem only by invalidating active state first. Record this as an implementation gap or qualify the conformance statement rather than documenting the stronger callback contract as already satisfied. Reproduction: reproduced — swift -module-cache-path "$V/.swift-module-cache" "$V/ios-cancellation-probe.swift" executes the unchanged cited close handler for an unshown current presentation and exits 1 with seen=true and survey dismissed recorded.

[turnipdabeets]

Fixed in d45e483: iOS now listed as a gap for close-before-shown.

[marandaneto]

blocking: Do not certify Flutter’s cancelled-delay report-back path — Flutter #627 does not satisfy the newly required host report-back guarantee: its _cancelPopupDelay deliberately suppresses onClosed, and showSurvey returns when that cancelled wait resolves false. Relying on native reservation does not implement the missing callback; a cancelled bottom-sheet presentation therefore cannot be described as conforming to the requirement that every handed-off survey report shown or closed. Native reset/teardown may independently clear its reservation, so this is not a claim that ordinary reset necessarily deadlocks; qualify the documented conformance and track the cancellation gap instead. Reproduction: reproduced — DART_SUPPRESS_ANALYTICS=true dart "$V/flutter-cancellation-probe.dart" executes the unchanged cited asynchronous display/cancellation methods and exits 1 with onShownCalls=0; onClosedCalls=0.

[turnipdabeets]

Fixed in d45e483: Flutter now listed as a gap for cancelled-delay report-back.