From 72c6c81c68687a7610a13873bdb174fe9ac44315 Mon Sep 17 00:00:00 2001 From: Anna Garcia Date: Wed, 7 Oct 2026 15:50:12 -0400 Subject: [PATCH 1/7] docs(react-native): document @posthog/react-native-plugin 3.0 requirements --- .../installation/react-native.mdx | 2 +- .../docs/libraries/react-native/index.mdx | 25 ++++++++++++++++--- .../installation/react-native.mdx | 2 +- 3 files changed, 24 insertions(+), 5 deletions(-) diff --git a/contents/docs/error-tracking/installation/react-native.mdx b/contents/docs/error-tracking/installation/react-native.mdx index eb01464c4fb9..d23ebf06afe7 100644 --- a/contents/docs/error-tracking/installation/react-native.mdx +++ b/contents/docs/error-tracking/installation/react-native.mdx @@ -16,6 +16,6 @@ import { ErrorTrackingReactNativeInstallationWrapper } from './_snippets/et-inst ## iOS dependency resolution for native crash capture -The `@posthog/react-native-plugin` package supports CocoaPods, the hybrid CocoaPods and Swift Package Manager path, and React Native's full Swift Package Manager integration. PostHog verifies the full path with an iOS-only React Native 0.87.1 app and React Native Community CLI 20.2.0. This path requires `@posthog/react-native-plugin` 2.4.0 or later, Xcode 16 or later, and an iOS 15.1 or later app deployment target. +The `@posthog/react-native-plugin` package supports CocoaPods, the hybrid CocoaPods and Swift Package Manager path, and React Native's full Swift Package Manager integration. PostHog verifies the full path with an iOS-only React Native 0.87.1 app and React Native Community CLI 20.2.0. This path requires `@posthog/react-native-plugin` 2.4.0 or later, Xcode 16 or later, and an iOS 15.1 or later app deployment target. `@posthog/react-native-plugin` 3.0 and later requires Xcode 26 or later and an iOS 15 or later deployment target on every path. See [iOS dependency paths for the React Native native plugin](/docs/libraries/react-native#choose-an-ios-dependency-path-for-the-native-plugin) for the requirements and setup steps. This verification does not cover Expo or other React Native versions. Use CocoaPods or the hybrid path unless you validate full Swift Package Manager for your configuration. diff --git a/contents/docs/libraries/react-native/index.mdx b/contents/docs/libraries/react-native/index.mdx index 3f0a799e63f5..1cf38641e2d3 100644 --- a/contents/docs/libraries/react-native/index.mdx +++ b/contents/docs/libraries/react-native/index.mdx @@ -30,13 +30,17 @@ import ReactNativeInstall from '../../integrate/_snippets/install-react-native.m ### Choose an iOS dependency path for the native plugin -The optional `@posthog/react-native-plugin` package adds native features such as session replay and native crash capture. Install it as described in the guide for the feature that you use. Then choose one iOS dependency path: +The optional `@posthog/react-native-plugin` package adds native features such as session replay and native crash capture. Install it as described in the guide for the feature that you use. + +`@posthog/react-native-plugin` 3.0 and later requires React Native 0.71 or later and, on every iOS dependency path, Xcode 26 or later and an iOS 15 or later deployment target (macOS 11 or later for React Native macOS apps). See [Upgrading to `@posthog/react-native-plugin` 3.0](#upgrading-to-posthogreact-native-plugin-30). + +Then choose one iOS dependency path: | Path | Requirements | What it resolves | | --- | --- | --- | | CocoaPods | A React Native project that uses CocoaPods | CocoaPods resolves the plugin and `posthog-ios`. This remains the default path. | | CocoaPods with `posthog-ios` through Swift Package Manager | React Native 0.75 or later and a CocoaPods project with dynamic frameworks | CocoaPods resolves the plugin. Swift Package Manager resolves `posthog-ios`. | -| Full Swift Package Manager | Verified with an iOS-only React Native 0.87.1 app and React Native Community CLI 20.2.0.

Requires `@posthog/react-native-plugin` 2.4.0 or later, Xcode 16 or later, and an iOS 15.1 or later app deployment target. | React Native's experimental Swift Package Manager integration resolves the plugin and `posthog-ios`. This path does not use CocoaPods. | +| Full Swift Package Manager | Verified with an iOS-only React Native 0.87.1 app and React Native Community CLI 20.2.0.

Requires `@posthog/react-native-plugin` 2.4.0 or later, Xcode 16 or later (Xcode 26 or later for plugin 3.0 and later), and an iOS 15.1 or later app deployment target. | React Native's experimental Swift Package Manager integration resolves the plugin and `posthog-ios`. This path does not use CocoaPods. | This verification does not cover Expo or other React Native versions. Use CocoaPods or the hybrid path unless you validate the full Swift Package Manager path for your configuration. @@ -88,7 +92,7 @@ npx react-native spm add --deintegrate --yes The `--deintegrate` option removes the complete CocoaPods integration from the iOS project. React Native then finds the plugin's `ios/Package.swift` manifest. Swift Package Manager resolves the plugin and `posthog-ios`. Do not run `pod install` for this path. -PostHog CI verifies this path with the configuration in the requirements table. The verified app sets its deployment target to iOS 15.1. The plugin package manifest has a separate iOS 15 minimum. The CocoaPods and hybrid paths keep the plugin podspec's iOS 13 minimum. +PostHog CI verifies this path with the configuration in the requirements table. The verified app sets its deployment target to iOS 15.1. The plugin package manifest has a separate iOS 15 minimum. On the CocoaPods and hybrid paths, the plugin podspec's minimum is iOS 15 from `@posthog/react-native-plugin` 3.0, and iOS 13 in earlier versions. @@ -693,6 +697,21 @@ const MyComponent = () => { } ``` +## Upgrading to `@posthog/react-native-plugin` 3.0 + +`@posthog/react-native-plugin` 3.0 uses `posthog-ios` 4.0 and requires: + +- React Native 0.71 or later +- Xcode 26 or later, on every iOS dependency path +- An iOS 15 or later deployment target, and macOS 11 or later for React Native macOS apps + +Apps that use the plugin only through `posthog-react-native` need no code changes. If your code calls the plugin directly: + +- Call `setup()` instead of the removed `start()` method. +- Pass `throttleDelayMs` instead of `iOSdebouncerDelayMs` or `androidDebouncerDelayMs`, which the plugin no longer reads. `posthog-react-native` still maps these deprecated options to `throttleDelayMs`. + +On iOS, native uploads (session replay and native crash reports) pause while cellular data is turned off for your app, instead of sending requests that fail. + ## Upgrading from V1, V2 to V3 or V3 to V4 V1 of this library utilised the underlying `posthog-ios` and `posthog-android` SDKs to do most of the work. Since the new version is written entirely in JS, using only Expo supported libraries, there are some changes to the way PostHog is configured as well as actually calling PostHog. diff --git a/contents/docs/session-replay/installation/react-native.mdx b/contents/docs/session-replay/installation/react-native.mdx index 49d9cf307278..bbc235c55e95 100644 --- a/contents/docs/session-replay/installation/react-native.mdx +++ b/contents/docs/session-replay/installation/react-native.mdx @@ -20,7 +20,7 @@ The native plugin supports three additive iOS dependency paths: - CocoaPods for the plugin and `posthog-ios`. This remains the default path. - CocoaPods for the plugin, with `posthog-ios` resolved through Swift Package Manager. -- React Native's experimental full Swift Package Manager integration, with no CocoaPods. PostHog verifies an iOS-only React Native 0.87.1 app with React Native Community CLI 20.2.0. This path requires `@posthog/react-native-plugin` 2.4.0 or later, Xcode 16 or later, and an iOS 15.1 or later app deployment target. +- React Native's experimental full Swift Package Manager integration, with no CocoaPods. PostHog verifies an iOS-only React Native 0.87.1 app with React Native Community CLI 20.2.0. This path requires `@posthog/react-native-plugin` 2.4.0 or later, Xcode 16 or later, and an iOS 15.1 or later app deployment target. `@posthog/react-native-plugin` 3.0 and later requires Xcode 26 or later and an iOS 15 or later deployment target on every path. See [iOS dependency paths for the React Native native plugin](/docs/libraries/react-native#choose-an-ios-dependency-path-for-the-native-plugin) for the requirements and setup steps. This verification does not cover Expo or other React Native versions. Use CocoaPods or the hybrid path unless you validate full Swift Package Manager for your configuration. From 60a9b000feb90377c2ba2a4df471219bb23107e7 Mon Sep 17 00:00:00 2001 From: Anna Garcia Date: Wed, 28 Oct 2026 11:32:32 -0400 Subject: [PATCH 2/7] docs(react-native): plugin 3.0 needs RN 0.75 and drops posthog.useSpm Covers PostHog/posthog-js#5449: posthog-ios always comes from SwiftPM, and screenshotModeBackgroundCapture is ignored on iOS. --- .../installation/react-native.mdx | 2 +- .../docs/libraries/react-native/index.mdx | 20 ++++++++++++++----- .../installation/react-native.mdx | 12 ++++++----- 3 files changed, 23 insertions(+), 11 deletions(-) diff --git a/contents/docs/error-tracking/installation/react-native.mdx b/contents/docs/error-tracking/installation/react-native.mdx index d23ebf06afe7..dd4c2710cdcc 100644 --- a/contents/docs/error-tracking/installation/react-native.mdx +++ b/contents/docs/error-tracking/installation/react-native.mdx @@ -16,6 +16,6 @@ import { ErrorTrackingReactNativeInstallationWrapper } from './_snippets/et-inst ## iOS dependency resolution for native crash capture -The `@posthog/react-native-plugin` package supports CocoaPods, the hybrid CocoaPods and Swift Package Manager path, and React Native's full Swift Package Manager integration. PostHog verifies the full path with an iOS-only React Native 0.87.1 app and React Native Community CLI 20.2.0. This path requires `@posthog/react-native-plugin` 2.4.0 or later, Xcode 16 or later, and an iOS 15.1 or later app deployment target. `@posthog/react-native-plugin` 3.0 and later requires Xcode 26 or later and an iOS 15 or later deployment target on every path. +The `@posthog/react-native-plugin` package supports CocoaPods, the hybrid CocoaPods and Swift Package Manager path, and React Native's full Swift Package Manager integration. PostHog verifies the full path with an iOS-only React Native 0.87.1 app and React Native Community CLI 20.2.0. This path requires `@posthog/react-native-plugin` 2.4.0 or later, Xcode 16 or later, and an iOS 15.1 or later app deployment target. `@posthog/react-native-plugin` 3.0 and later requires React Native 0.75 or later and, on every path, Xcode 26 or later and an iOS 15 or later deployment target. From 3.0, the CocoaPods path resolves `posthog-ios` through Swift Package Manager, so the separate hybrid path applies to 2.x only. See [iOS dependency paths for the React Native native plugin](/docs/libraries/react-native#choose-an-ios-dependency-path-for-the-native-plugin) for the requirements and setup steps. This verification does not cover Expo or other React Native versions. Use CocoaPods or the hybrid path unless you validate full Swift Package Manager for your configuration. diff --git a/contents/docs/libraries/react-native/index.mdx b/contents/docs/libraries/react-native/index.mdx index 1cf38641e2d3..5637be002e51 100644 --- a/contents/docs/libraries/react-native/index.mdx +++ b/contents/docs/libraries/react-native/index.mdx @@ -32,14 +32,14 @@ import ReactNativeInstall from '../../integrate/_snippets/install-react-native.m The optional `@posthog/react-native-plugin` package adds native features such as session replay and native crash capture. Install it as described in the guide for the feature that you use. -`@posthog/react-native-plugin` 3.0 and later requires React Native 0.71 or later and, on every iOS dependency path, Xcode 26 or later and an iOS 15 or later deployment target (macOS 11 or later for React Native macOS apps). See [Upgrading to `@posthog/react-native-plugin` 3.0](#upgrading-to-posthogreact-native-plugin-30). +`@posthog/react-native-plugin` 3.0 and later requires React Native 0.75 or later and, on every iOS dependency path, Xcode 26 or later and an iOS 15 or later deployment target (macOS 11 or later for React Native macOS apps). See [Upgrading to `@posthog/react-native-plugin` 3.0](#upgrading-to-posthogreact-native-plugin-30). Then choose one iOS dependency path: | Path | Requirements | What it resolves | | --- | --- | --- | -| CocoaPods | A React Native project that uses CocoaPods | CocoaPods resolves the plugin and `posthog-ios`. This remains the default path. | -| CocoaPods with `posthog-ios` through Swift Package Manager | React Native 0.75 or later and a CocoaPods project with dynamic frameworks | CocoaPods resolves the plugin. Swift Package Manager resolves `posthog-ios`. | +| CocoaPods | A React Native project that uses CocoaPods | CocoaPods resolves the plugin. From `@posthog/react-native-plugin` 3.0, Swift Package Manager resolves `posthog-ios`. In earlier versions, CocoaPods resolves it. This remains the default path. | +| CocoaPods with `posthog-ios` through Swift Package Manager | `@posthog/react-native-plugin` 2.x only. React Native 0.75 or later and a CocoaPods project with dynamic frameworks | CocoaPods resolves the plugin. Swift Package Manager resolves `posthog-ios`. From 3.0, the CocoaPods path does this by default. | | Full Swift Package Manager | Verified with an iOS-only React Native 0.87.1 app and React Native Community CLI 20.2.0.

Requires `@posthog/react-native-plugin` 2.4.0 or later, Xcode 16 or later (Xcode 26 or later for plugin 3.0 and later), and an iOS 15.1 or later app deployment target. | React Native's experimental Swift Package Manager integration resolves the plugin and `posthog-ios`. This path does not use CocoaPods. | This verification does not cover Expo or other React Native versions. Use CocoaPods or the hybrid path unless you validate the full Swift Package Manager path for your configuration. @@ -53,10 +53,12 @@ cd ios pod install ``` -The plugin podspec adds `posthog-ios` as a CocoaPods dependency. You do not need to add `posthog-ios` separately. +The plugin podspec adds `posthog-ios` for you. You do not need to add `posthog-ios` separately. From `@posthog/react-native-plugin` 3.0, the podspec adds it through Swift Package Manager with React Native's `spm_dependency` helper. Static libraries, static frameworks and dynamic frameworks all work. Earlier versions add it as a CocoaPods dependency. #### CocoaPods with `posthog-ios` through Swift Package Manager +This path applies to `@posthog/react-native-plugin` 2.x only. From 3.0, the CocoaPods path already resolves `posthog-ios` through Swift Package Manager and the plugin ignores `posthog.useSpm`. + Add the following property to `ios/Podfile.properties.json`: ```json @@ -701,10 +703,16 @@ const MyComponent = () => { `@posthog/react-native-plugin` 3.0 uses `posthog-ios` 4.0 and requires: -- React Native 0.71 or later +- React Native 0.75 or later - Xcode 26 or later, on every iOS dependency path - An iOS 15 or later deployment target, and macOS 11 or later for React Native macOS apps +On iOS, the plugin now always resolves `posthog-ios` through Swift Package Manager: + +- Remove `"posthog.useSpm"` from `ios/Podfile.properties.json` if you set it. The plugin no longer reads it. +- The plugin no longer needs `use_frameworks! :linkage => :dynamic`. Keep it only if another dependency needs it. +- Remove the legacy `posthog-react-native-session-replay` package if your app still depends on it. It pulls in `posthog-ios` 3.x, and the plugin uses 4.x. + Apps that use the plugin only through `posthog-react-native` need no code changes. If your code calls the plugin directly: - Call `setup()` instead of the removed `start()` method. @@ -712,6 +720,8 @@ Apps that use the plugin only through `posthog-react-native` need no code change On iOS, native uploads (session replay and native crash reports) pause while cellular data is turned off for your app, instead of sending requests that fail. +The experimental iOS session replay option `sessionReplayConfig.screenshotModeBackgroundCapture` no longer has an effect, because `posthog-ios` 4.0 removes it. + ## Upgrading from V1, V2 to V3 or V3 to V4 V1 of this library utilised the underlying `posthog-ios` and `posthog-android` SDKs to do most of the work. Since the new version is written entirely in JS, using only Expo supported libraries, there are some changes to the way PostHog is configured as well as actually calling PostHog. diff --git a/contents/docs/session-replay/installation/react-native.mdx b/contents/docs/session-replay/installation/react-native.mdx index bbc235c55e95..cfe21919f90f 100644 --- a/contents/docs/session-replay/installation/react-native.mdx +++ b/contents/docs/session-replay/installation/react-native.mdx @@ -16,14 +16,16 @@ import { SRReactNativeInstallationWrapper } from './_snippets/sr-installation-wr ## iOS dependency resolution -The native plugin supports three additive iOS dependency paths: +The native plugin supports these iOS dependency paths: -- CocoaPods for the plugin and `posthog-ios`. This remains the default path. -- CocoaPods for the plugin, with `posthog-ios` resolved through Swift Package Manager. -- React Native's experimental full Swift Package Manager integration, with no CocoaPods. PostHog verifies an iOS-only React Native 0.87.1 app with React Native Community CLI 20.2.0. This path requires `@posthog/react-native-plugin` 2.4.0 or later, Xcode 16 or later, and an iOS 15.1 or later app deployment target. `@posthog/react-native-plugin` 3.0 and later requires Xcode 26 or later and an iOS 15 or later deployment target on every path. +- CocoaPods for the plugin. This remains the default path. From `@posthog/react-native-plugin` 3.0, Swift Package Manager resolves `posthog-ios`. In earlier versions, CocoaPods resolves it. +- In `@posthog/react-native-plugin` 2.x only, CocoaPods for the plugin with `posthog-ios` resolved through Swift Package Manager, using the `posthog.useSpm` property. +- React Native's experimental full Swift Package Manager integration, with no CocoaPods. PostHog verifies an iOS-only React Native 0.87.1 app with React Native Community CLI 20.2.0. This path requires `@posthog/react-native-plugin` 2.4.0 or later, Xcode 16 or later, and an iOS 15.1 or later app deployment target. + +`@posthog/react-native-plugin` 3.0 and later requires React Native 0.75 or later and, on every path, Xcode 26 or later and an iOS 15 or later deployment target. See [iOS dependency paths for the React Native native plugin](/docs/libraries/react-native#choose-an-ios-dependency-path-for-the-native-plugin) for the requirements and setup steps. This verification does not cover Expo or other React Native versions. Use CocoaPods or the hybrid path unless you validate full Swift Package Manager for your configuration. ## Troubleshooting -- If session replay looks janky or drops frames on high-refresh-rate (120Hz ProMotion) iPhones, turn on the experimental `sessionReplayConfig.screenshotModeBackgroundCapture` option (iOS only, requires `posthog-react-native` 4.45.0 or higher) to move screenshot capture off the main thread. This can trigger Xcode's Main Thread Checker warnings, so disable it in your scheme's Run diagnostics if that happens. +- If session replay looks janky or drops frames on high-refresh-rate (120Hz ProMotion) iPhones, turn on the experimental `sessionReplayConfig.screenshotModeBackgroundCapture` option (iOS only, requires `posthog-react-native` 4.45.0 or higher and `@posthog/react-native-plugin` 2.x) to move screenshot capture off the main thread. This can trigger Xcode's Main Thread Checker warnings, so disable it in your scheme's Run diagnostics if that happens. From ed3828100ad44de6eaba54e4b602cc683c1c5ca4 Mon Sep 17 00:00:00 2001 From: Anna Garcia Date: Wed, 28 Oct 2026 11:49:14 -0400 Subject: [PATCH 3/7] docs(react-native): show the setup() argument structure for direct start() callers Co-Authored-By: Claude Opus 5.5 --- contents/docs/libraries/react-native/index.mdx | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/contents/docs/libraries/react-native/index.mdx b/contents/docs/libraries/react-native/index.mdx index 5637be002e51..207ca8f7fa2e 100644 --- a/contents/docs/libraries/react-native/index.mdx +++ b/contents/docs/libraries/react-native/index.mdx @@ -715,7 +715,18 @@ On iOS, the plugin now always resolves `posthog-ios` through Swift Package Manag Apps that use the plugin only through `posthog-react-native` need no code changes. If your code calls the plugin directly: -- Call `setup()` instead of the removed `start()` method. +- Call `setup()` instead of the removed `start()` method. `setup()` takes three arguments and reads the replay settings from `pluginConfig.sessionReplay`. Replay starts only when `sessionReplay.enabled` is `true`, which defaults to `false`: + + ```ts + // Before + start(sessionId, sdkOptions, sdkReplayConfig, decideReplayConfig) + + // After + setup(sessionId, sdkOptions, { + sessionReplay: { enabled: true, sdkReplayConfig, decideReplayConfig }, + }) + ``` + - Pass `throttleDelayMs` instead of `iOSdebouncerDelayMs` or `androidDebouncerDelayMs`, which the plugin no longer reads. `posthog-react-native` still maps these deprecated options to `throttleDelayMs`. On iOS, native uploads (session replay and native crash reports) pause while cellular data is turned off for your app, instead of sending requests that fail. From 139f5ca211400fd3d05e53760432d8b268565304 Mon Sep 17 00:00:00 2001 From: Anna Garcia Date: Fri, 30 Oct 2026 21:44:34 -0400 Subject: [PATCH 4/7] docs(react-native): add plugin 3.0 Podfile, native import and dSYM upgrade notes --- contents/docs/libraries/react-native/index.mdx | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/contents/docs/libraries/react-native/index.mdx b/contents/docs/libraries/react-native/index.mdx index 207ca8f7fa2e..f50d9e96b021 100644 --- a/contents/docs/libraries/react-native/index.mdx +++ b/contents/docs/libraries/react-native/index.mdx @@ -701,7 +701,7 @@ const MyComponent = () => { ## Upgrading to `@posthog/react-native-plugin` 3.0 -`@posthog/react-native-plugin` 3.0 uses `posthog-ios` 4.0 and requires: +`@posthog/react-native-plugin` 3.0 uses `posthog-ios` 4.0. For before-and-after examples and a checklist, see the [migration guide](https://github.com/PostHog/posthog-js/blob/main/packages/react-native-plugin/MIGRATION.md). The plugin requires: - React Native 0.75 or later - Xcode 26 or later, on every iOS dependency path @@ -712,6 +712,10 @@ On iOS, the plugin now always resolves `posthog-ios` through Swift Package Manag - Remove `"posthog.useSpm"` from `ios/Podfile.properties.json` if you set it. The plugin no longer reads it. - The plugin no longer needs `use_frameworks! :linkage => :dynamic`. Keep it only if another dependency needs it. - Remove the legacy `posthog-react-native-session-replay` package if your app still depends on it. It pulls in `posthog-ios` 3.x, and the plugin uses 4.x. +- Remove these Podfile settings if you use them, because `pod install` now fails with them: `:generate_multiple_pod_projects => true`, `:deduplicate_targets => false`, and targets that use the plugin with different `platform` or `use_frameworks!` settings. +- Make sure build machines can reach `https://github.com/PostHog/posthog-ios.git`, because Xcode now fetches `posthog-ios` from there. +- If your app target has `import PostHog`, check that it still compiles. React Native's helper adds the package only to the plugin's pod target. This case isn't tested, but if the import no longer resolves, add `posthog-ios` to your app target as a Swift package with a compatible version. +- If a custom dSYM upload script calls `${PODS_ROOT}/PostHog/build-tools/upload-symbols.sh`, change it to `${BUILD_DIR%/Build/*}/SourcePackages/checkouts/posthog-ios/build-tools/upload-symbols.sh`. The `uploadNativeSymbols` build phase from the Expo config plugin already checks both paths. Apps that use the plugin only through `posthog-react-native` need no code changes. If your code calls the plugin directly: From 08756c73c23f97b703c0922a64a88453729f5ba4 Mon Sep 17 00:00:00 2001 From: Anna Garcia Date: Fri, 30 Oct 2026 21:44:54 -0400 Subject: [PATCH 5/7] docs(error-tracking): use the Swift package dSYM script for React Native plugin 3.0 --- .../docs/error-tracking/upload-source-maps/react-native.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/contents/docs/error-tracking/upload-source-maps/react-native.mdx b/contents/docs/error-tracking/upload-source-maps/react-native.mdx index b5df0a274c3d..5749f8b01d9d 100644 --- a/contents/docs/error-tracking/upload-source-maps/react-native.mdx +++ b/contents/docs/error-tracking/upload-source-maps/react-native.mdx @@ -298,11 +298,11 @@ In Xcode, add a **Run Script** build phase to your main app target and place it -```bash file=CocoaPods +```bash file=CocoaPods (plugin 2.x) "${PODS_ROOT}/PostHog/build-tools/upload-symbols.sh" ``` -```bash file=Swift Package Manager +```bash file=Swift Package Manager (and plugin 3.0 and later) "${BUILD_DIR%/Build/*}/SourcePackages/checkouts/posthog-ios/build-tools/upload-symbols.sh" ``` From f91019937a68b2a9295e6b37583d0f0471648e3b Mon Sep 17 00:00:00 2001 From: Anna Garcia Date: Fri, 30 Oct 2026 21:45:04 -0400 Subject: [PATCH 6/7] docs(error-tracking): label the source-upload dSYM tabs for React Native plugin 3.0 --- .../docs/error-tracking/upload-source-maps/react-native.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/contents/docs/error-tracking/upload-source-maps/react-native.mdx b/contents/docs/error-tracking/upload-source-maps/react-native.mdx index 5749f8b01d9d..b6cd3f374d62 100644 --- a/contents/docs/error-tracking/upload-source-maps/react-native.mdx +++ b/contents/docs/error-tracking/upload-source-maps/react-native.mdx @@ -317,11 +317,11 @@ To also upload native source files for source-code context (iOS only), prefix th -```bash file=CocoaPods +```bash file=CocoaPods (plugin 2.x) POSTHOG_INCLUDE_SOURCE=1 "${PODS_ROOT}/PostHog/build-tools/upload-symbols.sh" ``` -```bash file=Swift Package Manager +```bash file=Swift Package Manager (and plugin 3.0 and later) POSTHOG_INCLUDE_SOURCE=1 "${BUILD_DIR%/Build/*}/SourcePackages/checkouts/posthog-ios/build-tools/upload-symbols.sh" ``` From 191fb50acadc32aaf9a1b1fd45b4570259e6d453 Mon Sep 17 00:00:00 2001 From: Anna Garcia Date: Fri, 30 Oct 2026 22:07:17 -0400 Subject: [PATCH 7/7] docs(react-native): note screenshot-only replay for plugin 3.0 --- contents/docs/libraries/react-native/index.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/contents/docs/libraries/react-native/index.mdx b/contents/docs/libraries/react-native/index.mdx index f50d9e96b021..64eaa468237d 100644 --- a/contents/docs/libraries/react-native/index.mdx +++ b/contents/docs/libraries/react-native/index.mdx @@ -737,6 +737,8 @@ On iOS, native uploads (session replay and native crash reports) pause while cel The experimental iOS session replay option `sessionReplayConfig.screenshotModeBackgroundCapture` no longer has an effect, because `posthog-ios` 4.0 removes it. +Session replay records only masked screenshots on iOS and Android, because `posthog-ios` 4.0 and `posthog-android` 4.0 remove wireframe capture. The plugin already forced screenshot mode, so your recordings don't change. If native code in your app sets `screenshotMode` (iOS) or `screenshot` (Android), remove it, because it no longer compiles. + ## Upgrading from V1, V2 to V3 or V3 to V4 V1 of this library utilised the underlying `posthog-ios` and `posthog-android` SDKs to do most of the work. Since the new version is written entirely in JS, using only Expo supported libraries, there are some changes to the way PostHog is configured as well as actually calling PostHog.