[turnipdabeets]

💡 Motivation and Context

These fix two Surveys gaps against the surveys spec:

• Wait period ("The survey wait period starts when a survey is shown"). Submitting or dismissing a survey SHALL NOT move the last-seen survey date. iOS writes the date on show, but setSurveySeen wrote it again on submit and dismiss, so seenSurveyWaitPeriodInDays counted from the close. A survey shown on day 0 and dismissed on day 2 kept a 7-day-wait survey hidden until day 9.
• Popup delay ("Survey popup delay"). A survey that hasn't reached the screen hasn't been shown: closing it SHALL NOT mark it seen or send an interaction event, and reset SHALL release the reservation. 3.x already has surveyPopupDelaySeconds in the default delegate (feat(surveys): support survey popup delay #520), and a custom PostHogSurveysDelegate can also delay. Two gaps:
  • A close reported before display marked the survey seen and sent survey dismissed.
  • reset() didn't cancel a survey waiting out its popup delay, so the previous user's survey still appeared after the delay, without a survey shown event.

Changes

• setSurveySeen no longer writes the last-seen date. Seen keys are unchanged.

• Each survey attempt records whether it was shown. The shown callback sets it, and so does the first answer, since an answer means the survey is on screen. The first answer also writes the date, but only for custom delegates that never call onSurveyShown.

• A close before the survey is shown releases the reservation and does nothing else: no seen key, no date, no survey dismissed, saved progress kept. It doesn't queue the next survey right away, so a delegate that can't display a survey doesn't get it re-rendered in a tight loop. The next normal trigger picks it up.

• reset() cancels a pending attempt from before the reset. With the default delegate it cancels the delayed display and leaves any survey already on screen alone. A custom delegate gets cleanupSurveys(). A survey already on screen keeps its current behavior.

• getNextSurveyStep and its helper move unchanged into PostHogSurveyMatching.swift. Without the move, PostHogSurveyIntegration.swift would be about 1,237 lines, over SwiftLint's 1,200-line error limit (it's 1,145 now).

• Patch changeset added.

• The reset hook is guarded with #if os(iOS) || TESTING and reads the delegate through _surveysConfig, because 3.x still supports iOS 13.

• Not done: the spec's optional (SHOULD) eligibility re-check when the delay ends. The default delegate owns the timer, so it isn't a small change.

Merging into 4.0

When main is next merged into chore/v4-remove-deprecated, use the 4.0 (!SWIFT_PACKAGE || Surveys) guard and surveysConfig for the reset hook, and add the behavior change to .changeset/v4-major-release.md and MIGRATION.md.

Behavior change

• The next survey can appear slightly sooner after a dismissal, since the wait period counts from the show.
• A close before display no longer sends survey dismissed or marks the survey seen.

💚 How did you test it?

New tests in PostHogSurveyEventsTest:

• Submitting or dismissing a survey shown 8 days earlier doesn't move the date, and a survey with a 7-day wait is eligible.
• A close before the survey is shown sends no event and marks nothing seen. The reservation is released and the survey stays eligible.
• reset() releases a survey that hasn't been shown, and the old attempt's callbacks report nothing.
• iOS only: a reset() during a 0.2 s popup delay means the survey is never displayed.

One existing test (resumed completion and dismissal preserve seen history) closed a resumed survey without ever showing it. It now calls the shown callback first, the way a real UI would.

macOS (SPM)

• make test filter=Survey: 173 tests in 27 suites passed.
• With only the test file applied on main (no fix), make test filter=PostHogSurveyEventsTest fails the three macOS tests with 9 issues.
• make lint: 0 serious violations, no files need formatting. The warnings are already on main.

iOS simulator (iPhone 17e, iOS 26.4.1)

xcodebuild test hung before the runner connected, so I built the test bundle and ran it inside the simulator with xctest:

xcodebuild build-for-testing -scheme PostHog -destination 'id=<sim>' -derivedDataPath <dd>
xcrun simctl boot <sim>
xcrun simctl spawn <sim> "$(xcrun --sdk iphonesimulator --show-sdk-platform-path)/Developer/Library/Xcode/Agents/xctest" \
  -XCTest PostHogTests.PostHogSurveyEventsTest <dd>/Build/Products/Testing-iphonesimulator/PostHogTests.xctest

Run	Result
PostHogSurveyEventsTest, this branch	49 tests passed, including the iOS-only popup-delay test
PostHogSurveyEventsTest, main with only the test file applied	All 4 new tests fail (11 issues), including the popup-delay test
-XCTest All, this branch	1,706 tests in 239 suites. 2 non-survey tests failed: changed beforeSend output is captured after relaunch and add() racing with flush(). They ran while I was compiling the example app on the same machine. Rerun alone, PostHogIdentityTests (44) and PostHogLogsQueueTests (31) both passed. Every survey test passed.

The first simulator build also caught an iOS 13 compile error: surveysConfig is iOS 15+ on 3.x, so the reset hook reads _surveysConfig.

Example app on the same simulator

I pointed PostHogExample at a local mock server that serves one popover survey and logs survey events. A launch argument either dismissed the survey 12 s after launch (through cleanupSurveys(), which goes through the same onSurveyClosed path as the close button) or called reset() 6 s after launch. I didn't commit those changes. I ran each scenario against main and this branch:

Scenario	main	This branch
Show a survey, dismiss it 12 s later	Shown at 18:39:02.406Z, dismissed at 18:39:14.727Z. Stored lastSeenSurveyDate was 18:39:14.726Z, the dismiss time	Shown at 18:39:25.806Z, dismissed at 18:39:38.124Z. Stored lastSeenSurveyDate was 18:39:25.805Z, the show time
8 s popup delay, reset() 6 s after launch	The previous user's survey appeared when the delay ended (on screen in the 10 s screenshot), with no survey shown event. The new user's attempt was then skipped ("Already displaying a survey"). No survey events were sent in 22 s	The previous user's survey never appeared (10 s screenshot shows no survey). The new user's attempt was scheduled when reset() ran and was shown 8.4 s later, with survey shown sent under the new distinct ID

📝 Checklist

• All commits are signed (see Commit signing)
• I reviewed the submitted code.
• I added tests to verify the changes.
• I updated the docs if needed.
• No breaking change or entry added to the changelog.

If releasing new changes

• Ran pnpm changeset to generate a changeset file

🤖 Agent context

Autonomy: Human-driven (agent-assisted)

Claude Code (Opus) wrote this with Bash, Read and Edit. The iOS simulator build caught surveysConfig being iOS 15+ on 3.x, hence the _surveysConfig read. Every new test was checked to fail without the fix.

🤖 Generated with Claude Code

[veria-ai]

PR overview

No security issues were found in this pull request.

Reviews

• 1bf5a65 — No new issues

[github-actions]

posthog-ios Compliance Report

Date: 2026-11-09T18:32:05.045645+00:00
Duration: 225881ms

⚠️ Some Tests Failed

46/47 tests passed, 1 failed

---

Capture Tests

⚠️ 29/30 tests passed, 1 failed

View Details

Test	Status	Duration
Format Validation.Event Has Required Fields	✅	2921ms
Format Validation.Event Has Uuid	✅	2755ms
Format Validation.Event Has Lib Properties	✅	2797ms
Format Validation.Distinct Id Is String	✅	445ms
Format Validation.Token Is Present	✅	2720ms
Format Validation.Custom Properties Preserved	✅	2646ms
Format Validation.Event Has Timestamp	✅	2719ms
Format Validation.Non Utc Event Timestamp Is Converted To Utc	✅	2781ms
Retry Behavior.Retries On 503	✅	12017ms
Retry Behavior.Does Not Retry On 400	✅	4725ms
Retry Behavior.Does Not Retry On 401	✅	4768ms
Retry Behavior.Respects Retry After Header	✅	7708ms
Retry Behavior.Implements Backoff	✅	21295ms
Retry Behavior.Retries On 500	✅	9252ms
Retry Behavior.Retries On 502	✅	9294ms
Retry Behavior.Retries On 504	✅	5243ms
Retry Behavior.Max Retries Respected	❌	21808ms
Deduplication.Generates Unique Uuids	✅	2873ms
Deduplication.Preserves Uuid On Retry	✅	9124ms
Deduplication.Preserves Uuid And Timestamp On Retry	✅	10392ms
Deduplication.Preserves Uuid And Timestamp On Batch Retry	✅	7803ms
Deduplication.No Duplicate Events In Batch	✅	2861ms
Deduplication.Different Events Have Different Uuids	✅	2717ms
Compression.Sends Gzip When Enabled	✅	2715ms
Batch Format.Uses Proper Batch Structure	✅	2698ms
Batch Format.Flush With No Events Sends Nothing	✅	212ms
Batch Format.Multiple Events Batched Together	✅	2877ms
Error Handling.Does Not Retry On 403	✅	5085ms
Error Handling.Does Not Retry On 413	✅	2392ms
Error Handling.Retries On 408	✅	8779ms

Failures

retry_behavior.max_retries_respected

Expected 4 requests, got 6

Feature_Flags Tests

✅ 17/17 tests passed

View Details

Test	Status	Duration
Request Payload.Request With Person Properties Device Id	✅	2744ms
Request Payload.Flags Request Uses V2 Query Param	✅	2779ms
Request Payload.Flags Request Hits Flags Path Not Decide	✅	2700ms
Request Payload.Flags Request Omits Authorization Header	✅	2767ms
Request Payload.Token In Flags Body Matches Init	✅	2765ms
Request Payload.Groups Round Trip	✅	2769ms
Request Payload.Groups Default To Empty Object	✅	2720ms
Request Payload.Disable Geoip False Propagates As Geoip Disable False	✅	2758ms
Request Payload.Disable Geoip Omitted Defaults To False	✅	2702ms
Request Payload.Flag Keys To Evaluate Contains Only Requested Key	✅	2803ms
Request Lifecycle.No Flags Request On Init Alone	✅	108ms
Request Lifecycle.No Flags Request On Normal Capture	✅	2752ms
Request Lifecycle.Two Flag Calls Produce Two Remote Requests	✅	5499ms
Request Lifecycle.Mock Response Value Is Returned To Caller	✅	2847ms
Retry Behavior.Retries Flags On 502	✅	2909ms
Retry Behavior.Retries Flags On 504	✅	2743ms
Side Effect Events.Get Feature Flag Captures Feature Flag Called Event	✅	3158ms