From f85b7b4475216c3f8659c4ffc6081e27ec0b1027 Mon Sep 17 00:00:00 2001 From: Anna Garcia Date: Wed, 4 Nov 2026 15:22:52 -0500 Subject: [PATCH 01/12] docs(onboarding): install posthog-ios 4.0 with Swift Package Manager only posthog-ios 4.0 is distributed only through Swift Package Manager and removes sessionReplayConfig.screenshotMode. Point the in-app and published iOS install snippets at from: "4.0.0", drop the CocoaPods snippets and the minVersionPod option, and drop screenshotMode from the in-app replay config. Co-Authored-By: Claude Opus 5.5 --- docs/onboarding/error-tracking/ios.tsx | 5 +---- docs/onboarding/logs/ios.tsx | 5 +---- docs/onboarding/product-analytics/ios.tsx | 17 +---------------- docs/onboarding/session-replay/ios.tsx | 16 ++-------------- .../sdks/sdk-install-instructions/ios.tsx | 15 +++------------ 5 files changed, 8 insertions(+), 50 deletions(-) diff --git a/docs/onboarding/error-tracking/ios.tsx b/docs/onboarding/error-tracking/ios.tsx index 39228b70e4e7..ad47d3c73f03 100644 --- a/docs/onboarding/error-tracking/ios.tsx +++ b/docs/onboarding/error-tracking/ios.tsx @@ -6,10 +6,7 @@ import { StepDefinition } from '../steps' export const getIOSSteps = (ctx: OnboardingComponentsContext): StepDefinition[] => { const { CodeBlock, Markdown, CalloutBox, dedent } = ctx - const installSteps = getIOSStepsPA(ctx, { - minVersionPod: '3.56', - minVersionSPM: '3.56.0', - }) + const installSteps = getIOSStepsPA(ctx) const exceptionAutocaptureStep: StepDefinition = { title: 'Set up exception autocapture', diff --git a/docs/onboarding/logs/ios.tsx b/docs/onboarding/logs/ios.tsx index 8aacebcac842..271399a6d9d3 100644 --- a/docs/onboarding/logs/ios.tsx +++ b/docs/onboarding/logs/ios.tsx @@ -6,10 +6,7 @@ import { StepDefinition } from '../steps' export const getIOSSteps = (ctx: OnboardingComponentsContext): StepDefinition[] => { const { CodeBlock, Markdown, dedent } = ctx - const installSteps = getIOSStepsPA(ctx, { - minVersionPod: '3.58', - minVersionSPM: '3.58.0', - }) + const installSteps = getIOSStepsPA(ctx) const sendLogStep: StepDefinition = { title: 'Send a log', diff --git a/docs/onboarding/product-analytics/ios.tsx b/docs/onboarding/product-analytics/ios.tsx index 7b820d183c9c..6fd2f9196e37 100644 --- a/docs/onboarding/product-analytics/ios.tsx +++ b/docs/onboarding/product-analytics/ios.tsx @@ -7,14 +7,12 @@ export const getIOSInstallSteps = ( options?: { includeExperimentalSpi?: boolean experimentalDescription?: string - minVersionPod?: string minVersionSPM?: string } ): StepDefinition[] => { const { CodeBlock, Markdown, CalloutBox, dedent } = ctx - const podVersion = options?.minVersionPod || '3.56' - const spmVersion = options?.minVersionSPM || '3.56.0' + const spmVersion = options?.minVersionSPM || '4.0.0' return [ { @@ -41,18 +39,6 @@ export const getIOSInstallSteps = ( }, ]} /> - Or add PostHog to your Podfile: - ${podVersion}" - `, - }, - ]} - /> ), }, @@ -126,7 +112,6 @@ export const getIOSSteps = ( options?: { includeExperimentalSpi?: boolean experimentalDescription?: string - minVersionPod?: string minVersionSPM?: string } ): StepDefinition[] => [...getIOSInstallSteps(ctx, options), getIOSEventStep(ctx)] diff --git a/docs/onboarding/session-replay/ios.tsx b/docs/onboarding/session-replay/ios.tsx index ed8ecd6be01d..98e3d15da7a0 100644 --- a/docs/onboarding/session-replay/ios.tsx +++ b/docs/onboarding/session-replay/ios.tsx @@ -12,19 +12,7 @@ export const getIOSSteps = (ctx: OnboardingComponentsContext): StepDefinition[] badge: 'required', content: ( <> - Add PostHog to your Podfile: - 3.56" - `, - }, - ]} - /> - Or install via Swift Package Manager: + Install via Swift Package Manager: {'pod "PostHog", "~> 3.56"'} -} - function IOSInstallSPMSnippet(): JSX.Element { return ( {`dependencies: [ - .package(url: "https://github.com/PostHog/posthog-ios.git", from: "3.56.0") + .package(url: "https://github.com/PostHog/posthog-ios.git", from: "4.0.0") ]`} ) @@ -35,10 +31,7 @@ function IOSSetupSnippet(props: iOSSetupProps): JSX.Element { config.sessionReplay = true // choose whether to mask images or text config.sessionReplayConfig.maskAllImages = false - config.sessionReplayConfig.maskAllTextInputs = true - // screenshot is disabled by default - // The screenshot may contain sensitive information, use with caution - config.sessionReplayConfig.screenshotMode = true`, + config.sessionReplayConfig.maskAllTextInputs = true`, props.includeSurveys && `config.surveys = true`, ] .filter(Boolean) @@ -71,9 +64,7 @@ class AppDelegate: NSObject, UIApplicationDelegate { export function SDKInstallIOSInstructions(props: iOSSetupProps): JSX.Element { return ( <> -

Install via CocoaPods

- -

Or Install via SPM

+

Install via Swift Package Manager

Configure

From a7b8f2aa7d299f439ec34cc620e160e6863f99c9 Mon Sep 17 00:00:00 2001 From: Anna Garcia Date: Thu, 5 Nov 2026 15:59:35 -0500 Subject: [PATCH 02/12] docs(onboarding): drop CocoaPods dSYM path and 3.x leftovers for posthog-ios 4.0 - iOS dSYM upload instructions: keep only the Swift Package Manager script path. - Session replay: remove the stale "requires 3.6.0 or higher" callout. - Surveys: drop the `#available(iOS 15.0, *)` wrapper; 4.0's minimum is iOS 15. - Product analytics: remove the unused `minVersionSPM` option. Co-Authored-By: Claude Opus 5.5 --- docs/onboarding/product-analytics/ios.tsx | 6 +----- docs/onboarding/session-replay/ios.tsx | 6 ------ docs/onboarding/surveys/ios.tsx | 5 +---- .../IOSSourceMapsInstructions.tsx | 12 +----------- 4 files changed, 3 insertions(+), 26 deletions(-) diff --git a/docs/onboarding/product-analytics/ios.tsx b/docs/onboarding/product-analytics/ios.tsx index 6fd2f9196e37..b9f3c79187e9 100644 --- a/docs/onboarding/product-analytics/ios.tsx +++ b/docs/onboarding/product-analytics/ios.tsx @@ -7,13 +7,10 @@ export const getIOSInstallSteps = ( options?: { includeExperimentalSpi?: boolean experimentalDescription?: string - minVersionSPM?: string } ): StepDefinition[] => { const { CodeBlock, Markdown, CalloutBox, dedent } = ctx - const spmVersion = options?.minVersionSPM || '4.0.0' - return [ { title: 'Install dependency', @@ -33,7 +30,7 @@ export const getIOSInstallSteps = ( file: 'Package.swift', code: dedent` dependencies: [ - .package(url: "https://github.com/PostHog/posthog-ios.git", from: "${spmVersion}") + .package(url: "https://github.com/PostHog/posthog-ios.git", from: "4.0.0") ] `, }, @@ -112,7 +109,6 @@ export const getIOSSteps = ( options?: { includeExperimentalSpi?: boolean experimentalDescription?: string - minVersionSPM?: string } ): StepDefinition[] => [...getIOSInstallSteps(ctx, options), getIOSEventStep(ctx)] diff --git a/docs/onboarding/session-replay/ios.tsx b/docs/onboarding/session-replay/ios.tsx index 98e3d15da7a0..d17c3a3f59f3 100644 --- a/docs/onboarding/session-replay/ios.tsx +++ b/docs/onboarding/session-replay/ios.tsx @@ -26,12 +26,6 @@ export const getIOSSteps = (ctx: OnboardingComponentsContext): StepDefinition[] }, ]} /> - - - Session replay requires PostHog iOS SDK version 3.6.0 or higher. We recommend always using - the latest version. - - ), }, diff --git a/docs/onboarding/surveys/ios.tsx b/docs/onboarding/surveys/ios.tsx index eb7965d28a7e..ee44bc24839e 100644 --- a/docs/onboarding/surveys/ios.tsx +++ b/docs/onboarding/surveys/ios.tsx @@ -29,10 +29,7 @@ function getSurveysIOSSteps(ctx: OnboardingComponentsContext): StepDefinition[] let POSTHOG_HOST = "" let config = PostHogConfig(projectToken: POSTHOG_PROJECT_TOKEN, host: POSTHOG_HOST) - // Surveys require iOS 15.0 or later - if #available(iOS 15.0, *) { - config.surveys = true - } + config.surveys = true PostHogSDK.shared.setup(config) `, diff --git a/frontend/src/scenes/onboarding/error-tracking/source-maps/automated-technologies/IOSSourceMapsInstructions.tsx b/frontend/src/scenes/onboarding/error-tracking/source-maps/automated-technologies/IOSSourceMapsInstructions.tsx index bbdb44bf35b2..9e694c50914a 100644 --- a/frontend/src/scenes/onboarding/error-tracking/source-maps/automated-technologies/IOSSourceMapsInstructions.tsx +++ b/frontend/src/scenes/onboarding/error-tracking/source-maps/automated-technologies/IOSSourceMapsInstructions.tsx @@ -124,17 +124,13 @@ export function IOSSourceMapsInstructions(): JSX.Element { Click the + button and select New Run Script Phase
  • Make sure it's set to run last (after "Copy Bundle Resources" or similar)
    • -
  • Add the appropriate script for your package manager:
    • +
  • Add the following script:
    • -

    Swift Package Manager:

    {'${BUILD_DIR%/Build/*}/SourcePackages/checkouts/posthog-ios/build-tools/upload-symbols.sh'} -

    CocoaPods:

    - {'${PODS_ROOT}/PostHog/build-tools/upload-symbols.sh'} -

    4. Optional: Include source code context

    By default, only debug symbols are uploaded. To include source code snippets in your stack traces (for @@ -145,18 +141,12 @@ export function IOSSourceMapsInstructions(): JSX.Element {

  • Set the environment variable when calling the upload script:
    • -

    Swift Package Manager:

    { 'POSTHOG_INCLUDE_SOURCE=1 ${BUILD_DIR%/Build/*}/SourcePackages/checkouts/posthog-ios/build-tools/upload-symbols.sh' } -

    CocoaPods:

    - - {'POSTHOG_INCLUDE_SOURCE=1 ${PODS_ROOT}/PostHog/build-tools/upload-symbols.sh'} - -

    Note: Enabling this flag uploads your source code to PostHog's servers. This is disabled by default. Only enable it if your organization's security and data-governance policies permit From 0082156d215b3831a6e73f2c8aa82cf6fbb195d2 Mon Sep 17 00:00:00 2001 From: Anna Garcia Date: Thu, 5 Nov 2026 19:25:33 -0500 Subject: [PATCH 03/12] docs(replay): drop wireframe mode from ios replay onboarding --- docs/onboarding/session-replay/ios.tsx | 20 +++++--------------- 1 file changed, 5 insertions(+), 15 deletions(-) diff --git a/docs/onboarding/session-replay/ios.tsx b/docs/onboarding/session-replay/ios.tsx index d17c3a3f59f3..0e02cfea281f 100644 --- a/docs/onboarding/session-replay/ios.tsx +++ b/docs/onboarding/session-replay/ios.tsx @@ -93,25 +93,15 @@ export const getIOSSteps = (ctx: OnboardingComponentsContext): StepDefinition[] // requires SDK version 3.41.1 or higher. config.sessionReplayConfig.captureNetworkTelemetry = true - // Whether replays are created using high quality screenshots. Default is false. - // Required for SwiftUI. - // If disabled, replays are created using wireframes instead. - // The screenshot may contain sensitive information, so use with caution - config.sessionReplayConfig.screenshotMode = true - - // Experimental. Only applies when \`screenshotMode\` is enabled. - // Moves screenshot rendering off the main thread, which reduces jank - // on high refresh rate (120Hz ProMotion) displays. May trigger Xcode's - // Main Thread Checker and briefly freeze the app on the first capture. - // Default is false. Requires SDK version 3.58.1 or higher. - config.sessionReplayConfig.screenshotModeBackgroundCapture = false + // Replays are recorded as masked screenshots, so mask anything sensitive. + // Before SDK version 4.0, also set config.sessionReplayConfig.screenshotMode = true, + // otherwise replays are recorded as wireframes and SwiftUI screens aren't recorded. // Minimum time (in seconds) between snapshots. Default is 1.0s. // Snapshots are taken when views lay out, so this caps how often one // can be captured rather than setting a fixed frame rate. // Lower values can make playback smoother, at the cost of more // capture work on the device. - // Note: called \`debouncerDelay\` before version 3.21.0 config.sessionReplayConfig.throttleDelay = 1.0 // Sample rate for session recordings. A value between 0.0 and 1.0. @@ -138,8 +128,8 @@ export const getIOSSteps = (ctx: OnboardingComponentsContext): StepDefinition[] - SwiftUI is only supported if the `screenshotMode` option is enabled. Custom views and - WebViews also require screenshot mode for full support. + SDK version 4.0 and later record SwiftUI, custom views and WebViews as screenshots. Earlier + versions only support them if the `screenshotMode` option is enabled. From 00569f1fd3d9593b61ba1f677a903226cb62d4d3 Mon Sep 17 00:00:00 2001 From: Anna Garcia Date: Fri, 6 Nov 2026 13:13:16 -0500 Subject: [PATCH 04/12] docs(onboarding): point CocoaPods users to posthog-ios 3.x Co-Authored-By: Claude Opus 5.5 --- docs/onboarding/product-analytics/ios.tsx | 7 +++++++ .../onboarding/sdks/sdk-install-instructions/ios.tsx | 9 +++++++++ 2 files changed, 16 insertions(+) diff --git a/docs/onboarding/product-analytics/ios.tsx b/docs/onboarding/product-analytics/ios.tsx index b9f3c79187e9..b89cc13b9f9d 100644 --- a/docs/onboarding/product-analytics/ios.tsx +++ b/docs/onboarding/product-analytics/ios.tsx @@ -36,6 +36,13 @@ export const getIOSInstallSteps = ( }, ]} /> + + + { + 'Version 4 is only published to Swift Package Manager. Version 3 stays on CocoaPods (`pod "PostHog", "~> 3.0"`) but gets no new releases. To switch, see [upgrading from version 3 to version 4](https://posthog.com/docs/libraries/ios#upgrading-from-version-3-to-version-4).' + } + + ), }, diff --git a/frontend/src/scenes/onboarding/sdks/sdk-install-instructions/ios.tsx b/frontend/src/scenes/onboarding/sdks/sdk-install-instructions/ios.tsx index e5ddd46936f5..98feafe09796 100644 --- a/frontend/src/scenes/onboarding/sdks/sdk-install-instructions/ios.tsx +++ b/frontend/src/scenes/onboarding/sdks/sdk-install-instructions/ios.tsx @@ -1,6 +1,7 @@ import { useValues } from 'kea' import { CodeSnippet, Language } from 'lib/components/CodeSnippet' +import { Link } from 'lib/lemon-ui/Link' import { apiHostOrigin } from 'lib/utils/apiHost' import { teamLogic } from 'scenes/teamLogic' @@ -66,6 +67,14 @@ export function SDKInstallIOSInstructions(props: iOSSetupProps): JSX.Element { <>

    Install via Swift Package Manager

    +

    + Using CocoaPods? Version 4 is only published to Swift Package Manager. Version 3 stays on CocoaPods ( + pod "PostHog", "~> 3.0") but gets no new releases. To switch, see{' '} + + upgrading from version 3 to version 4 + + . +

    Configure

    From 654911e5266597fc616ff56b214138f89671e45b Mon Sep 17 00:00:00 2001 From: Anna Garcia Date: Sun, 8 Nov 2026 12:15:17 -0500 Subject: [PATCH 05/12] docs(onboarding): add iOS 15 and Xcode 26 requirements to SPM install --- docs/onboarding/product-analytics/ios.tsx | 5 ++++- docs/onboarding/session-replay/ios.tsx | 5 ++++- .../scenes/onboarding/sdks/sdk-install-instructions/ios.tsx | 3 +++ 3 files changed, 11 insertions(+), 2 deletions(-) diff --git a/docs/onboarding/product-analytics/ios.tsx b/docs/onboarding/product-analytics/ios.tsx index b89cc13b9f9d..4001a034be0b 100644 --- a/docs/onboarding/product-analytics/ios.tsx +++ b/docs/onboarding/product-analytics/ios.tsx @@ -22,7 +22,10 @@ export const getIOSInstallSteps = ( {options.experimentalDescription} )} - Install via Swift Package Manager: + + Install via Swift Package Manager. PostHog requires Xcode 26 or later, and iOS 15, macOS 11, + tvOS 15, watchOS 10, or visionOS 1 or later. + - Install via Swift Package Manager: + + Install via Swift Package Manager. PostHog requires Xcode 26 or later, and iOS 15, macOS 11, + tvOS 15, watchOS 10, or visionOS 1 or later. +

    Install via Swift Package Manager

    +

    + PostHog requires Xcode 26 or later, and iOS 15, macOS 11, tvOS 15, watchOS 10, or visionOS 1 or later. +

    Using CocoaPods? Version 4 is only published to Swift Package Manager. Version 3 stays on CocoaPods ( From cf9196a65fc5a671bf830dd44c296de405ffbc05 Mon Sep 17 00:00:00 2001 From: Anna Garcia Date: Tue, 10 Nov 2026 14:50:55 -0500 Subject: [PATCH 06/12] docs(ios): match posthog.com wording for CocoaPods 3.x availability --- docs/onboarding/product-analytics/ios.tsx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/onboarding/product-analytics/ios.tsx b/docs/onboarding/product-analytics/ios.tsx index 4001a034be0b..de7d1307bc63 100644 --- a/docs/onboarding/product-analytics/ios.tsx +++ b/docs/onboarding/product-analytics/ios.tsx @@ -42,7 +42,7 @@ export const getIOSInstallSteps = ( { - 'Version 4 is only published to Swift Package Manager. Version 3 stays on CocoaPods (`pod "PostHog", "~> 3.0"`) but gets no new releases. To switch, see [upgrading from version 3 to version 4](https://posthog.com/docs/libraries/ios#upgrading-from-version-3-to-version-4).' + 'Version 4 is only published to Swift Package Manager. Version 3 stays on CocoaPods (`pod "PostHog", "~> 3.0"`), but [CocoaPods trunk becomes read-only on December 2, 2026](https://blog.cocoapods.org/CocoaPods-Specs-Repo/). After that, existing 3.x versions stay installable, but new releases only ship through Swift Package Manager. To switch, see [upgrading from version 3 to version 4](https://posthog.com/docs/libraries/ios#upgrading-from-version-3-to-version-4).' } From b99ed4feb9e15447b6306e1efe01f24369fe7b89 Mon Sep 17 00:00:00 2001 From: Anna Garcia Date: Tue, 10 Nov 2026 14:50:56 -0500 Subject: [PATCH 07/12] docs(ios): note that WebViews are masked whole while masking is on --- docs/onboarding/session-replay/ios.tsx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/onboarding/session-replay/ios.tsx b/docs/onboarding/session-replay/ios.tsx index eb3ec7db28a1..a6ada24ff975 100644 --- a/docs/onboarding/session-replay/ios.tsx +++ b/docs/onboarding/session-replay/ios.tsx @@ -132,7 +132,8 @@ export const getIOSSteps = (ctx: OnboardingComponentsContext): StepDefinition[] SDK version 4.0 and later record SwiftUI, custom views and WebViews as screenshots. Earlier - versions only support them if the `screenshotMode` option is enabled. + versions only support them if the `screenshotMode` option is enabled. A `WKWebView` is + masked whole while `maskAllTextInputs` or `maskAllImages` is on, as in this snippet. From e38262ec3cc3c18568f0d48e23fbcf9c5a546e7a Mon Sep 17 00:00:00 2001 From: Anna Garcia Date: Tue, 10 Nov 2026 14:50:56 -0500 Subject: [PATCH 08/12] chore(onboarding): delete the unrendered iOS install instructions component --- .../sdks/sdk-install-instructions/index.tsx | 1 - .../sdks/sdk-install-instructions/ios.tsx | 102 ------------------ 2 files changed, 103 deletions(-) delete mode 100644 frontend/src/scenes/onboarding/sdks/sdk-install-instructions/ios.tsx diff --git a/frontend/src/scenes/onboarding/sdks/sdk-install-instructions/index.tsx b/frontend/src/scenes/onboarding/sdks/sdk-install-instructions/index.tsx index 45ffdf34a991..e770980e8ffa 100644 --- a/frontend/src/scenes/onboarding/sdks/sdk-install-instructions/index.tsx +++ b/frontend/src/scenes/onboarding/sdks/sdk-install-instructions/index.tsx @@ -7,7 +7,6 @@ export * from './elixir' export * from './flutter' export * from './framer' export * from './go' -export * from './ios' export * from './js-web' export * from './laravel' export * from './nodejs' diff --git a/frontend/src/scenes/onboarding/sdks/sdk-install-instructions/ios.tsx b/frontend/src/scenes/onboarding/sdks/sdk-install-instructions/ios.tsx deleted file mode 100644 index 14aba67b9cff..000000000000 --- a/frontend/src/scenes/onboarding/sdks/sdk-install-instructions/ios.tsx +++ /dev/null @@ -1,102 +0,0 @@ -import { useValues } from 'kea' - -import { CodeSnippet, Language } from 'lib/components/CodeSnippet' -import { Link } from 'lib/lemon-ui/Link' -import { apiHostOrigin } from 'lib/utils/apiHost' -import { teamLogic } from 'scenes/teamLogic' - -export interface iOSSetupProps { - includeReplay?: boolean - includeSurveys?: boolean - includeExperimentalSpi?: boolean -} - -function IOSInstallSPMSnippet(): JSX.Element { - return ( - - {`dependencies: [ - .package(url: "https://github.com/PostHog/posthog-ios.git", from: "4.0.0") -]`} - - ) -} - -function IOSSetupSnippet(props: iOSSetupProps): JSX.Element { - const { currentTeam } = useValues(teamLogic) - - const configOptions = [ - props.includeReplay && - `// check https://posthog.com/docs/session-replay/installation?tab=iOS - // for more config and to learn about how we capture sessions on mobile - // and what to expect - config.sessionReplay = true - // choose whether to mask images or text - config.sessionReplayConfig.maskAllImages = false - config.sessionReplayConfig.maskAllTextInputs = true`, - props.includeSurveys && `config.surveys = true`, - ] - .filter(Boolean) - .join('\n') - - const configSection = configOptions ? configOptions : '' - - return ( - - {`import Foundation -${props.includeExperimentalSpi ? '@_spi(Experimental) import PostHog' : 'import PostHog'} -import UIKit - -class AppDelegate: NSObject, UIApplicationDelegate { - func application(_: UIApplication, didFinishLaunchingWithOptions _: [UIApplication.LaunchOptionsKey: Any]? = nil) -> Bool { - let POSTHOG_PROJECT_TOKEN = "${currentTeam?.api_token}" - let POSTHOG_HOST = "${apiHostOrigin()}" - - let config = PostHogConfig(projectToken: POSTHOG_PROJECT_TOKEN, host: POSTHOG_HOST) - ${configSection} - PostHogSDK.shared.setup(config) - - return true - } -}`} - - ) -} - -export function SDKInstallIOSInstructions(props: iOSSetupProps): JSX.Element { - return ( - <> -

    Install via Swift Package Manager

    -

    - PostHog requires Xcode 26 or later, and iOS 15, macOS 11, tvOS 15, watchOS 10, or visionOS 1 or later. -

    - -

    - Using CocoaPods? Version 4 is only published to Swift Package Manager. Version 3 stays on CocoaPods ( - pod "PostHog", "~> 3.0") but gets no new releases. To switch, see{' '} - - upgrading from version 3 to version 4 - - . -

    -

    Configure

    - - - ) -} - -export function SDKInstallIOSTrackScreenInstructions(): JSX.Element { - return ( - <> -

    - With configuration.captureScreenViews set as true, PostHog will try to record - all screen changes automatically. -

    -

    - If you want to manually send a new screen capture event, use the screen function. -

    - {`PostHogSDK.shared.screen("Dashboard", properties: ["fromIcon": "bottom"])`} - - ) -} From a162a47b26c79f284419830fb87b180aece3aa3b Mon Sep 17 00:00:00 2001 From: Anna Garcia Date: Tue, 10 Nov 2026 15:05:16 -0500 Subject: [PATCH 09/12] docs(ios): add the cocoapods note to the replay install step Co-Authored-By: Claude Opus 5.5 --- docs/onboarding/session-replay/ios.tsx | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/onboarding/session-replay/ios.tsx b/docs/onboarding/session-replay/ios.tsx index a6ada24ff975..9a22e0ac1d36 100644 --- a/docs/onboarding/session-replay/ios.tsx +++ b/docs/onboarding/session-replay/ios.tsx @@ -29,6 +29,13 @@ export const getIOSSteps = (ctx: OnboardingComponentsContext): StepDefinition[] }, ]} /> + + + { + 'Version 4 is only published to Swift Package Manager. Version 3 stays on CocoaPods (`pod "PostHog", "~> 3.0"`), but [CocoaPods trunk becomes read-only on December 2, 2026](https://blog.cocoapods.org/CocoaPods-Specs-Repo/). After that, existing 3.x versions stay installable, but new releases only ship through Swift Package Manager. To switch, see [upgrading from version 3 to version 4](https://posthog.com/docs/libraries/ios#upgrading-from-version-3-to-version-4).' + } + + ), }, From 3a1758fff09fda34d0056b07dae2a60aca81d460 Mon Sep 17 00:00:00 2001 From: Anna Garcia Date: Thu, 12 Nov 2026 10:51:36 -0500 Subject: [PATCH 10/12] docs(ios): keep screenshotModeBackgroundCapture in the replay onboarding snippet posthog-ios 4.0 keeps the option (posthog-ios#1052), so it stays documented next to the other replay settings. --- docs/onboarding/session-replay/ios.tsx | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/onboarding/session-replay/ios.tsx b/docs/onboarding/session-replay/ios.tsx index 9a22e0ac1d36..b09bec1c0773 100644 --- a/docs/onboarding/session-replay/ios.tsx +++ b/docs/onboarding/session-replay/ios.tsx @@ -107,6 +107,13 @@ export const getIOSSteps = (ctx: OnboardingComponentsContext): StepDefinition[] // Before SDK version 4.0, also set config.sessionReplayConfig.screenshotMode = true, // otherwise replays are recorded as wireframes and SwiftUI screens aren't recorded. + // Experimental. Moves screenshot capture to a background queue, which can + // reduce main-thread hangs and dropped frames on complex screens or high + // refresh rate (120Hz ProMotion) displays. May trigger Xcode's Main Thread + // Checker and briefly freeze the app on the first capture. + // Default is false. Requires SDK version 3.58.1 or higher. + config.sessionReplayConfig.screenshotModeBackgroundCapture = false + // Minimum time (in seconds) between snapshots. Default is 1.0s. // Snapshots are taken when views lay out, so this caps how often one // can be captured rather than setting a fixed frame rate. From 765b3e040bfe0e8c01ae1aabf663f4f918b060f2 Mon Sep 17 00:00:00 2001 From: Anna Garcia Date: Thu, 12 Nov 2026 10:56:38 -0500 Subject: [PATCH 11/12] docs(ios): document screenshotScale in the replay onboarding snippet posthog-ios has had the experimental option since 3.93.0 (posthog-ios#994); Android and React Native already list it. --- docs/onboarding/session-replay/ios.tsx | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/onboarding/session-replay/ios.tsx b/docs/onboarding/session-replay/ios.tsx index b09bec1c0773..4d99ab1d0ba1 100644 --- a/docs/onboarding/session-replay/ios.tsx +++ b/docs/onboarding/session-replay/ios.tsx @@ -114,6 +114,13 @@ export const getIOSSteps = (ctx: OnboardingComponentsContext): StepDefinition[] // Default is false. Requires SDK version 3.58.1 or higher. config.sessionReplayConfig.screenshotModeBackgroundCapture = false + // Experimental. Screenshot resolution as a fraction of the screen's native + // resolution, from 0.1 to 1.0. With no value, captures one pixel per point, + // which is a third of native resolution on a 3x device. Higher values give + // sharper replays at the cost of capture time and upload size. + // Default is nil. Requires SDK version 3.93.0 or higher. + config.sessionReplayConfig.screenshotScale = nil + // Minimum time (in seconds) between snapshots. Default is 1.0s. // Snapshots are taken when views lay out, so this caps how often one // can be captured rather than setting a fixed frame rate. From 40a6a4ea25ab5cca32263de6bbe9eefec8807a22 Mon Sep 17 00:00:00 2001 From: Anna Garcia Date: Thu, 12 Nov 2026 14:44:39 -0500 Subject: [PATCH 12/12] docs(onboarding): link the iOS migration page and fix the dSYM CLI minimum - Point the CocoaPods callouts at /docs/libraries/ios/migration. The /docs/libraries/ios#upgrading-from-version-3-to-version-4 anchor goes away when posthog.com#22061 replaces the iOS pages with the generated reference. - The dSYM upload script rejects posthog-cli below 0.7.7, so say 0.7.7. - Drop the unused includeExperimentalSpi and experimentalDescription options. Co-Authored-By: Claude Opus 5.5 --- docs/onboarding/product-analytics/ios.tsx | 28 +++++-------------- docs/onboarding/session-replay/ios.tsx | 2 +- .../IOSSourceMapsInstructions.tsx | 2 +- 3 files changed, 9 insertions(+), 23 deletions(-) diff --git a/docs/onboarding/product-analytics/ios.tsx b/docs/onboarding/product-analytics/ios.tsx index de7d1307bc63..b1a2eac84e8d 100644 --- a/docs/onboarding/product-analytics/ios.tsx +++ b/docs/onboarding/product-analytics/ios.tsx @@ -2,13 +2,7 @@ import { OnboardingComponentsContext, createInstallation } from 'scenes/onboardi import { StepDefinition } from '../steps' -export const getIOSInstallSteps = ( - ctx: OnboardingComponentsContext, - options?: { - includeExperimentalSpi?: boolean - experimentalDescription?: string - } -): StepDefinition[] => { +export const getIOSInstallSteps = (ctx: OnboardingComponentsContext): StepDefinition[] => { const { CodeBlock, Markdown, CalloutBox, dedent } = ctx return [ @@ -17,11 +11,6 @@ export const getIOSInstallSteps = ( badge: 'required', content: ( <> - {options?.experimentalDescription && ( - - {options.experimentalDescription} - - )} Install via Swift Package Manager. PostHog requires Xcode 26 or later, and iOS 15, macOS 11, tvOS 15, watchOS 10, or visionOS 1 or later. @@ -42,7 +31,7 @@ export const getIOSInstallSteps = ( { - 'Version 4 is only published to Swift Package Manager. Version 3 stays on CocoaPods (`pod "PostHog", "~> 3.0"`), but [CocoaPods trunk becomes read-only on December 2, 2026](https://blog.cocoapods.org/CocoaPods-Specs-Repo/). After that, existing 3.x versions stay installable, but new releases only ship through Swift Package Manager. To switch, see [upgrading from version 3 to version 4](https://posthog.com/docs/libraries/ios#upgrading-from-version-3-to-version-4).' + 'Version 4 is only published to Swift Package Manager. Version 3 stays on CocoaPods (`pod "PostHog", "~> 3.0"`), but [CocoaPods trunk becomes read-only on December 2, 2026](https://blog.cocoapods.org/CocoaPods-Specs-Repo/). After that, existing 3.x versions stay installable, but new releases only ship through Swift Package Manager. To switch, see the [iOS migration guide](https://posthog.com/docs/libraries/ios/migration).' } @@ -62,7 +51,7 @@ export const getIOSInstallSteps = ( file: 'AppDelegate.swift', code: dedent` import Foundation - ${options?.includeExperimentalSpi ? '@_spi(Experimental) ' : ''}import PostHog + import PostHog import UIKit class AppDelegate: NSObject, UIApplicationDelegate { @@ -114,12 +103,9 @@ export const getIOSEventStep = (ctx: OnboardingComponentsContext): StepDefinitio } } -export const getIOSSteps = ( - ctx: OnboardingComponentsContext, - options?: { - includeExperimentalSpi?: boolean - experimentalDescription?: string - } -): StepDefinition[] => [...getIOSInstallSteps(ctx, options), getIOSEventStep(ctx)] +export const getIOSSteps = (ctx: OnboardingComponentsContext): StepDefinition[] => [ + ...getIOSInstallSteps(ctx), + getIOSEventStep(ctx), +] export const IOSInstallation = createInstallation(getIOSSteps) diff --git a/docs/onboarding/session-replay/ios.tsx b/docs/onboarding/session-replay/ios.tsx index 4d99ab1d0ba1..9bd227afc6b1 100644 --- a/docs/onboarding/session-replay/ios.tsx +++ b/docs/onboarding/session-replay/ios.tsx @@ -32,7 +32,7 @@ export const getIOSSteps = (ctx: OnboardingComponentsContext): StepDefinition[] { - 'Version 4 is only published to Swift Package Manager. Version 3 stays on CocoaPods (`pod "PostHog", "~> 3.0"`), but [CocoaPods trunk becomes read-only on December 2, 2026](https://blog.cocoapods.org/CocoaPods-Specs-Repo/). After that, existing 3.x versions stay installable, but new releases only ship through Swift Package Manager. To switch, see [upgrading from version 3 to version 4](https://posthog.com/docs/libraries/ios#upgrading-from-version-3-to-version-4).' + 'Version 4 is only published to Swift Package Manager. Version 3 stays on CocoaPods (`pod "PostHog", "~> 3.0"`), but [CocoaPods trunk becomes read-only on December 2, 2026](https://blog.cocoapods.org/CocoaPods-Specs-Repo/). After that, existing 3.x versions stay installable, but new releases only ship through Swift Package Manager. To switch, see the [iOS migration guide](https://posthog.com/docs/libraries/ios/migration).' } diff --git a/frontend/src/scenes/onboarding/error-tracking/source-maps/automated-technologies/IOSSourceMapsInstructions.tsx b/frontend/src/scenes/onboarding/error-tracking/source-maps/automated-technologies/IOSSourceMapsInstructions.tsx index 84d2a1d719d7..ef8b9b155b5c 100644 --- a/frontend/src/scenes/onboarding/error-tracking/source-maps/automated-technologies/IOSSourceMapsInstructions.tsx +++ b/frontend/src/scenes/onboarding/error-tracking/source-maps/automated-technologies/IOSSourceMapsInstructions.tsx @@ -12,7 +12,7 @@ export function IOSSourceMapsInstructions(): JSX.Element {

    1. Install and authenticate the PostHog CLI

    The PostHog CLI handles dSYM upload for iOS apps. iOS dSYM support requires{' '} - CLI version 0.7.0 or later. Install it using one of these methods: + CLI version 0.7.7 or later. Install it using one of these methods:

    npm:

    npm install -g @posthog/cli