[turnipdabeets]

💡 Motivation and Context

Closes #557

The 4.0 major release branch. Its first change removes every public API that is already marked deprecated; the other 4.0 changes are listed under "Also on this branch".

Important

Don't merge yet. This PR targets main without changesets pre mode, so merging it publishes 4.0.0. It stays open until everything under "Before merging" is in, which keeps main free for 3.x fixes in the meantime.

Removed	Replacement
PostHogConfig.apiKey, init(apiKey:), init(apiKey:host:)	projectToken, init(projectToken:), init(projectToken:host:)
PostHogConfig.propertiesSanitizer, PostHogPropertiesSanitizer	PostHogConfig.setBeforeSend(_:)
PostHogConfig.evaluationEnvironments	evaluationContexts
PostHogConfig.remoteConfig	none, it was a no-op
PostHogSDK.getFeatureFlagPayload(_:)	getFeatureFlagResult(_:sendFeatureFlagEvent:)?.payload
PostHogSessionReplayConfig.debouncerDelay	throttleDelay
PostHogSessionReplayConfig.maskPhotoLibraryImages	none, it was a no-op

Public API change: this is a breaking removal, see the api/posthog-ios.public-api.txt diff.

Left in place on purpose:

• The deprecated members in PostHog/Utils/Reachability.swift, which is internal vendored code.
• PostHogConfig(apiKey:) in scripts/downgrade-compatibility-smoke, which compiles against 3.48.0.
• The internal PostHogEvent.apiKey and PostHogRemoteConfig.getFeatureFlagPayload.
• The storage migrations migrateLegacyStorage (added in 3.20) and mergeLegacyContainerIfNeeded (the app-group merge, added in 3.27). Both run on every init, but removing them would cost data. If someone updates an app straight from an older version to 4.x, their users lose their distinct ID and any queued events. In the last 7 days (US), about 8% of iOS SDK end-users were on an app build older than 3.27, and about 6% of apps had not shipped 3.27 or later. The app-group merge only affects apps that set appGroupIdentifier, so its share is smaller. We'll revisit in a later major.

Wrapper SDKs: posthog-flutter called getFeatureFlagPayload; PostHog/posthog-flutter#630 moves it off. The React Native plugin calls none of the removed APIs. Both pin posthog-ios below 4.0.

Also on this branch

This branch is the 4.0 integration branch. Each item below was reviewed and merged as its own PR. Their changesets are combined into one release entry, .changeset/v4-major-release.md.

• Platforms and toolchain:
  • iOS 15 minimum (chore!: raise minimum iOS deployment target to 15 #876).
  • macOS 11, tvOS 15 and watchOS 10 minimums (chore!: raise minimum macOS to 11, tvOS to 15 and watchOS to 10 #906).
  • Xcode 26 / swift-tools-version: 6.2, with Package@swift-5.9.swift removed (chore!: require Xcode 26 (swift-tools-version 6.2) #898).
• Package traits: the new SessionReplay, CrashReporting and Surveys SwiftPM traits, on by default (feat: add SessionReplay and CrashReporting package traits #916).
• Removed or changed APIs:
  • wrapper-only APIs moved behind SPI (chore!: hide wrapper-only APIs behind SPI for v4 #874)
  • PostHogDataMode.cellular (chore!: remove PostHogDataMode.cellular for v4 #890)
  • console log types renamed to PostHogConsoleLog* (chore!: rename console log types to PostHogConsoleLog* for v4 #912)
  • reloadFeatureFlags callback receives the reload result (chore!: pass the reload result to reloadFeatureFlags' callback #913)
  • malformed flag payloads return nil (chore!: return nil for malformed feature flag payloads #903)
  • wireframe replay capture (chore!: remove wireframe session replay capture #907)
  • screenshotModeBackgroundCapture (chore!: remove experimental screenshotModeBackgroundCapture #937)
  • the PostHogSDK.didReceiveFeatureFlags notification: use onFeatureFlags(_:), which reports the flags and load errors per SDK instance. posthog-flutter moves to the listener in chore!: adopt posthog-ios 4.0 and posthog-android 4.0 posthog-flutter#649. This one lands through chore!: remove the didReceiveFeatureFlags notification #965.
• Behavior:
  • The v2 queue migration is removed: 2.x queue files and their top-level $set are dropped; 3.x migrations are kept (chore!: remove the v2 legacy queue migration for v4 #875).
  • Lifecycle events no longer send the legacy version and build (chore!: drop legacy version and build from lifecycle events #905).
  • The vendored Reachability is replaced with NWPathMonitor (chore!: replace vendored Reachability with NWPathMonitor #909).
• CI and workflows:
  • Build and test jobs move to macos-15 with Xcode 26.0.1.
  • The Swift 5.3 / Xcode 15.4 CocoaPods job is replaced by a minimum-toolchain job (Xcode 26.0.1).
  • New jobs build and test with package traits off (buildSdkSpmNoTraits, testNoTraits).

Distribution: Swift Package Manager only

4.0 is published to Swift Package Manager only, not CocoaPods. CocoaPods trunk goes read-only on 2026-12-02, so any 4.x pod would stop getting updates within weeks. Pod builds also always compile every trait in, so CocoaPods users can't leave out replay or crash reporting. 3.x stays on CocoaPods until the lock, and the CocoaPods-to-SPM notice goes in the README, the changelog and the migration guide.

Cost for the React Native plugin, which resolves posthog-ios through CocoaPods by default and supports SPM only as an opt-in (posthog.useSpm):

• Its minimum React Native rises from 0.71 to 0.75, the first release with the spm_dependency helper.
• No Podfile linkage change is needed: static libraries, static frameworks and dynamic frameworks all build, and Expo needs no expo-build-properties change (verified in chore(react-native-plugin)!: resolve posthog-ios through Swift Package Manager posthog-js#5449).
• The plugin's 3.0 release has to make SPM the default before it can adopt posthog-ios 4.0; chore(react-native-plugin)!: resolve posthog-ios through Swift Package Manager posthog-js#5449 does that.

posthog_flutter needs the same check, since it ships both CocoaPods and SPM.

Wrapper SDK releases

posthog-ios 4.0 ships with a major release of each wrapper that embeds it. Each adoption PR waits until 4.0 is published.

Wrapper	Release PR	Adopts posthog-ios 4.0	Docs
posthog_flutter 6.0	PostHog/posthog-flutter#637	PostHog/posthog-flutter#649	PostHog/posthog.com#20924
@posthog/react-native-plugin 3.0	PostHog/posthog-js#5194	PostHog/posthog-js#5237, plus PostHog/posthog-js#5236 if #907 ships	PostHog/posthog.com#20922

Before merging

Follow-up PRs target this branch; each folds its line into the combined changeset.

• feat!: send events through capture v1 and add captureAi #938: send analytics events through capture v1.
• feat: add experimental GPU screenshot capture for session replay #911: GPU screenshot capture (rebased onto this branch).
• fix: accept plain closure arrays in setBeforeSend without a runtime trap #974: accept plain closure arrays in setBeforeSend(_:) instead of crashing at runtime.
• chore!: remove PostHogSessionReplayConfig.screenshotMode #973: remove screenshotMode instead of ignoring it.
• chore!: remove the didReceiveFeatureFlags notification #965: remove the didReceiveFeatureFlags notification.
• chore!: publish 4.0 to Swift Package Manager only #972: SPM-only release, with RELEASING.md and the CocoaPods notice.
• chore!: remove the public API of disabled package traits #975: remove the public API of traits that are turned off, and snapshot that API in CI.
• fix(replay): mask content drawn outside a view's bounds #976: replay masking gaps found in review (unclipped images, text attachments, text shadows, children of masked controls).
• chore: 4.0 fix-it stubs for removed APIs and review nits #977: unavailable fix-its for renamed and removed types, plus review nits.
• docs: add a 3.x to 4.0 migration guide #978: MIGRATION.md covering all of 4.0, starting with the changes the compiler doesn't flag.

💚 How did you test it?

• main is merged in through 3.92.5.
• make test passes locally (909 tests, macOS).
• The iOS SDK builds locally, via make apiUpdate.
• Not run locally: make build for the other platforms and example apps, and the iOS simulator test job.
• Tests that only covered the removed aliases are deleted.

📝 Checklist

• 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

The changeset is major and was written by hand in the changeset format. The release workflow runs on main, so merging this PR publishes 4.0.0.

🤖 Agent context

Autonomy: Human-driven (agent-assisted)

• Written with Claude Code (Opus 5.5).
• Scope is limited to declarations already carrying @available(*, deprecated), plus the code, tests and comments that only existed to support them.
• Docs on posthog.com that mention the removed options are not updated here.

🤖 Generated with Claude Code

[greptile-apps]

This review was skipped because it would exceed your organization's monthly flex usage limit. Raise the limit in billing settings or wait until the next billing period resets limits.

[github-actions]

posthog-ios Compliance Report

Date: 2026-10-29T15:28:24.928520+00:00
Duration: 241947ms

⚠️ Some Tests Failed

44/47 tests passed, 3 failed

---

Capture Tests

⚠️ 27/30 tests passed, 3 failed

View Details

Test	Status	Duration
Format Validation.Event Has Required Fields	❌	882ms
Format Validation.Event Has Uuid	❌	635ms
Format Validation.Event Has Lib Properties	✅	3876ms
Format Validation.Distinct Id Is String	✅	2848ms
Format Validation.Token Is Present	✅	3016ms
Format Validation.Custom Properties Preserved	✅	632ms
Format Validation.Event Has Timestamp	✅	2999ms
Format Validation.Non Utc Event Timestamp Is Converted To Utc	✅	2732ms
Retry Behavior.Retries On 503	✅	11805ms
Retry Behavior.Does Not Retry On 400	✅	4930ms
Retry Behavior.Does Not Retry On 401	✅	4879ms
Retry Behavior.Respects Retry After Header	✅	7780ms
Retry Behavior.Implements Backoff	✅	21358ms
Retry Behavior.Retries On 500	✅	9350ms
Retry Behavior.Retries On 502	✅	9273ms
Retry Behavior.Retries On 504	✅	9384ms
Retry Behavior.Max Retries Respected	❌	21765ms
Deduplication.Generates Unique Uuids	✅	3169ms
Deduplication.Preserves Uuid On Retry	✅	9230ms
Deduplication.Preserves Uuid And Timestamp On Retry	✅	16265ms
Deduplication.Preserves Uuid And Timestamp On Batch Retry	✅	7848ms
Deduplication.No Duplicate Events In Batch	✅	3030ms
Deduplication.Different Events Have Different Uuids	✅	3291ms
Compression.Sends Gzip When Enabled	✅	2956ms
Batch Format.Uses Proper Batch Structure	✅	2844ms
Batch Format.Flush With No Events Sends Nothing	✅	373ms
Batch Format.Multiple Events Batched Together	✅	2965ms
Error Handling.Does Not Retry On 403	✅	4900ms
Error Handling.Does Not Retry On 413	✅	4727ms
Error Handling.Retries On 408	✅	8845ms

Failures

format_validation.event_has_required_fields

Expected 1 requests, got 0

format_validation.event_has_uuid

No requests recorded

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	✅	2881ms
Request Payload.Flags Request Uses V2 Query Param	✅	2885ms
Request Payload.Flags Request Hits Flags Path Not Decide	✅	2767ms
Request Payload.Flags Request Omits Authorization Header	✅	2893ms
Request Payload.Token In Flags Body Matches Init	✅	2906ms
Request Payload.Groups Round Trip	✅	2742ms
Request Payload.Groups Default To Empty Object	✅	2843ms
Request Payload.Disable Geoip False Propagates As Geoip Disable False	✅	2682ms
Request Payload.Disable Geoip Omitted Defaults To False	✅	2820ms
Request Payload.Flag Keys To Evaluate Contains Only Requested Key	✅	2802ms
Request Lifecycle.No Flags Request On Init Alone	✅	110ms
Request Lifecycle.No Flags Request On Normal Capture	✅	2923ms
Request Lifecycle.Two Flag Calls Produce Two Remote Requests	✅	5434ms
Request Lifecycle.Mock Response Value Is Returned To Caller	✅	2777ms
Retry Behavior.Retries Flags On 502	✅	2887ms
Retry Behavior.Retries Flags On 504	✅	2766ms
Side Effect Events.Get Feature Flag Captures Feature Flag Called Event	✅	2973ms

[greptile-apps]

[High risk] Removes public API surface for iOS SDK major version.

The PR appears safe to merge; no actionable regression was identified.

_{Reviews (1) · Last reviewed commit: "chore!: remove deprecated public APIs fo..."}

[posthog]

PostHog Review · Standard · reviewed 1fb0c40: 1 Must fix. This pull request is large, so the review ran in 4 parts with less depth than usual.

This is review round 9 on this pull request. When findings keep coming back in the same code, the approach is usually the problem. Before the next fix, check whether a different design would remove the whole class of findings.

[turnipdabeets]

Thanks ioannisj! On the top-level points:

1. CocoaPods: going SPM-only in chore!: publish 4.0 to Swift Package Manager only #972. It updates RELEASING.md with what happens after the trunk lock, and the description spells out the React Native plugin cost (RN ≥ 0.75 and SPM by default, in chore(react-native-plugin)!: resolve posthog-ios through Swift Package Manager posthog-js#5449).
2. Merge timing: keeping the base on main, but chore!: iOS Major Release 4.0 #873 stays open until feat!: send events through capture v1 and add captureAi #938, feat: add experimental GPU screenshot capture for session replay #911 and the follow-ups land. The checklist is under "Before merging" in the description.
3. Last 3.x: we're skipping it. chore: 4.0 fix-it stubs for removed APIs and review nits #977 adds unavailable renamed/message fix-its for the removals apps are likely to hit, and docs: add a 3.x to 4.0 migration guide #978 covers the rest.
4. Migration guide: docs: add a 3.x to 4.0 migration guide #978 adds MIGRATION.md, starting with the changes the compiler won't flag.

[posthog]

PostHog Review · Standard · reviewed 732dc7d: 1 Should fix. This pull request is large, so the review ran in 4 parts with less depth than usual.

This is review round 10 on this pull request. When findings keep coming back in the same code, the approach is usually the problem. Before the next fix, check whether a different design would remove the whole class of findings.

[marandaneto]

keep PRs like this in draft until its ready to go so its out of our review list