Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
22 commits
Select commit Hold shift + click to select a range
72c6c81
docs(react-native): document @posthog/react-native-plugin 3.0 require…
turnipdabeets Oct 7, 2026
60a9b00
docs(react-native): plugin 3.0 needs RN 0.75 and drops posthog.useSpm
turnipdabeets Oct 28, 2026
ed38281
docs(react-native): show the setup() argument structure for direct st…
turnipdabeets Oct 28, 2026
139f5ca
docs(react-native): add plugin 3.0 Podfile, native import and dSYM up…
turnipdabeets Oct 31, 2026
08756c7
docs(error-tracking): use the Swift package dSYM script for React Nat…
turnipdabeets Oct 31, 2026
f910199
docs(error-tracking): label the source-upload dSYM tabs for React Nat…
turnipdabeets Oct 31, 2026
191fb50
docs(react-native): note screenshot-only replay for plugin 3.0
turnipdabeets Oct 31, 2026
ddc9092
Merge master into docs/react-native-plugin-3
turnipdabeets Nov 5, 2026
31ba7aa
docs(react-native): add posthog-android 4.0 notes to the plugin 3.0 u…
turnipdabeets Nov 6, 2026
9bae6be
docs(react-native): add setAppLanguage(), the pod conflict guard, and…
turnipdabeets Nov 8, 2026
0ee0072
docs(react-native): mark the hybrid path 2.x-only, list proxy headers…
turnipdabeets Nov 9, 2026
84039cc
docs(react-native): cover plugin 3.0 native event changes, masking an…
turnipdabeets Nov 10, 2026
7260b20
docs: fix Vale errors (en dashes, straight quotes)
turnipdabeets Nov 10, 2026
b40faf8
Merge branch 'master' into docs/react-native-plugin-3
turnipdabeets Nov 10, 2026
b3f0b5f
docs(react-native): call the plugin's native exceptions fatal JavaScr…
turnipdabeets Nov 10, 2026
efa766d
docs(react-native): use the US date format in the proxy note
turnipdabeets Nov 10, 2026
b5b5fa7
docs(react-native): move the app language section to its own PR
turnipdabeets Nov 12, 2026
d8d8bc7
docs(react-native): note dropped replay frames when fast scrolling ov…
turnipdabeets Nov 12, 2026
e3fed76
docs(react-native): keep screenshotModeBackgroundCapture for plugin 3.0
turnipdabeets Nov 12, 2026
2e937de
Merge branch 'master' into docs/react-native-plugin-3
turnipdabeets Nov 13, 2026
d223ec7
docs(react-native): name the dSYM script tabs so their plugin version…
turnipdabeets Nov 13, 2026
3715ef4
docs(react-native): use iOSCaptureMethod for background replay capture
turnipdabeets Nov 17, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 4 additions & 5 deletions contents/docs/_snippets/react-native-cocoapods-notice.mdx
Original file line number Diff line number Diff line change
@@ -1,8 +1,7 @@
> **CocoaPods is becoming read-only.** [CocoaPods has announced](https://blog.cocoapods.org/CocoaPods-Specs-Repo/) the following schedule for its public specs repository:
> **CocoaPods is becoming read-only.** [CocoaPods trunk becomes read-only on December 2, 2026](https://blog.cocoapods.org/CocoaPods-Specs-Repo/), and `posthog-ios` 4.0 and later is only published through Swift Package Manager (SPM).
>
> - November 2–6, 2026: A read-only dry run will prevent us from publishing new PostHog iOS SDK versions to CocoaPods.
> - December 2, 2026 onward: The repository will be permanently read-only. New PostHog iOS SDK versions will only be available through Swift Package Manager (SPM).
> `@posthog/react-native-plugin` 3.0 and later always resolves `posthog-ios` through SPM, including on the CocoaPods path, so upgrading the plugin is enough. See [Upgrading to `@posthog/react-native-plugin` 3.0](/docs/libraries/react-native#upgrading-to-posthogreact-native-plugin-30).
>
> Existing iOS SDK versions will remain available through CocoaPods. To keep receiving iOS SDK updates, migrate the native plugin's `posthog-ios` dependency to SPM using the [hybrid CocoaPods and SPM setup](/docs/libraries/react-native#cocoapods-with-posthog-ios-through-swift-package-manager), or use [full SPM integration](/docs/libraries/react-native#full-swift-package-manager) if your app supports it. The hybrid path keeps CocoaPods for the plugin and other React Native dependencies.
> Plugin 2.x pins `posthog-ios` 3.92.x on every iOS dependency path, including the hybrid and full SPM setups, so switching paths doesn't bring newer iOS SDK versions. To get `posthog-ios` 4.0 and later, upgrade to plugin 3.0.
>
> This change does not affect `@posthog/react-native-plugin` releases on npm or Android.
> This change doesn't affect `@posthog/react-native-plugin` releases on npm or Android.
4 changes: 2 additions & 2 deletions contents/docs/error-tracking/installation/react-native.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,6 @@ import AgentIntegrationSection from "../../components/AgentIntegrationSection.md

</ReactNativeCocoaPodsNotice>

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 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.
See [iOS dependency paths for the native React 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, on `@posthog/react-native-plugin` 2.x, the hybrid path) unless you validate full Swift Package Manager for your configuration.
14 changes: 7 additions & 7 deletions contents/docs/error-tracking/upload-source-maps/react-native.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@ Then use our standard [CLI approach](/docs/error-tracking/upload-source-maps/cli

<CalloutBox icon="IconInfo" title="Expo 50 or later" type="fyi">

Automatic source map injection works only in React Native apps using Expo 50 or later, as it relies on Expo’s built-in [debug ID](https://docs.expo.dev/versions/latest/config/metro/#source-map-debug-id) injection.
Automatic source map injection works only in React Native apps using Expo 50 or later, as it relies on Expo's built-in [debug ID](https://docs.expo.dev/versions/latest/config/metro/#source-map-debug-id) injection.

</CalloutBox>

Expand Down Expand Up @@ -119,7 +119,7 @@ The plugin accepts the following options:
| --- | --- | --- | --- |
| `disableSandboxing` | `boolean` | `true` | iOS only. When `true`, sets `ENABLE_USER_SCRIPT_SANDBOXING=NO` on your main app target's Xcode build configurations during `expo prebuild`. This lets the source map upload script read `.git/` (for release metadata) and lets stock Expo projects build without manually declaring input/output files on every script phase. |
| `skipOnConflict` | `boolean` | `false` | Adds `--skip-on-conflict` to JavaScript source map uploads on iOS and Android. Use this when the same build can upload the same source maps more than once and you want duplicate uploads to be skipped instead of failing. Requires `posthog-react-native` 4.49.1 or later. When `uploadNativeSymbols` is enabled, it also applies to native iOS dSYM uploads: a build whose dSYM already exists in PostHog with different content skips the upload and keeps the existing symbols instead of failing. The dSYM behavior requires `posthog-react-native` 4.56.1 or later, `posthog-ios` 3.64.7 or later, and `posthog-cli` 0.7.12 or later. |
| `dotenvFile` | `string` | – | Path to a dotenv file containing your `POSTHOG_CLI_*` credentials (API key, project ID, optional host), relative to the project root or absolute. During `expo prebuild` the path is wired into every upload hook as `POSTHOG_CLI_DOTENV_FILE` — an Xcode build setting on iOS and a `posthog.dotenvFile` entry in `android/gradle.properties` on Android — so the JavaScript source map, dSYM, and ProGuard/R8 mapping uploads all read credentials from the file regardless of how the native build is started. Real environment variables take precedence and a missing file only logs a warning, so the same config works unchanged in CI. Requires `posthog-react-native` 4.60.0 or later and `posthog-cli` 0.8.4 or later (older CLIs ignore the variable). |
| `dotenvFile` | `string` | – | Path to a dotenv file containing your `POSTHOG_CLI_*` credentials (API key, project ID, optional host), relative to the project root or absolute. During `expo prebuild` the path is wired into every upload hook as `POSTHOG_CLI_DOTENV_FILE` – an Xcode build setting on iOS and a `posthog.dotenvFile` entry in `android/gradle.properties` on Android – so the JavaScript source map, dSYM, and ProGuard/R8 mapping uploads all read credentials from the file regardless of how the native build is started. Real environment variables take precedence and a missing file only logs a warning, so the same config works unchanged in CI. Requires `posthog-react-native` 4.60.0 or later and `posthog-cli` 0.8.4 or later (older CLIs ignore the variable). |

Example opting out of the sandbox change:

Expand All @@ -137,7 +137,7 @@ Example opting out of the sandbox change:

`disableSandboxing: false` is intended for organizations with compliance requirements that forbid disabling Xcode's user script sandbox. With the opt-out:

- iOS source map uploads continue to work — errors still symbolicate
- iOS source map uploads continue to work – errors still symbolicate
- Git metadata will not be attached to iOS releases (the UI chip shown for Android rows will be missing on iOS rows)
- Your project must already have every build-phase script (yours, Expo's, CocoaPods-generated) declaring its inputs and outputs, otherwise the build will fail

Expand Down Expand Up @@ -251,7 +251,7 @@ Symbolicated native crashes need all three of these working together:

Both platforms upload through `posthog-cli`, which must be installed and authenticated – the same setup covered in the **Download CLI** and **Authenticate** steps above. The Android `.so` debug symbol upload needs `posthog-cli` 0.7.32 or later. In CI/CD builds (such as EAS Build), set the `POSTHOG_CLI_API_KEY` and `POSTHOG_CLI_PROJECT_ID` environment variables (and `POSTHOG_CLI_HOST` for EU). See [authenticating the CLI](/docs/error-tracking/upload-source-maps/cli) for the full list.

For local builds, the easiest way to supply these credentials is the `dotenvFile` plugin option described in the **Upload** step — it covers the native symbol uploads on both platforms too. On bare React Native, you get the same behavior by adding `posthog.dotenvFile=../.env` to `android/gradle.properties` (relative paths resolve against the `android/` directory; the mapping upload needs `posthog-android-gradle-plugin` 1.4.0 or later) and, on iOS, defining a `POSTHOG_CLI_DOTENV_FILE` build setting (for example `$(SRCROOT)/../.env`) on your app target.
For local builds, the easiest way to supply these credentials is the `dotenvFile` plugin option described in the **Upload** step – it covers the native symbol uploads on both platforms too. On bare React Native, you get the same behavior by adding `posthog.dotenvFile=../.env` to `android/gradle.properties` (relative paths resolve against the `android/` directory; the mapping upload needs `posthog-android-gradle-plugin` 1.4.0 or later) and, on iOS, defining a `POSTHOG_CLI_DOTENV_FILE` build setting (for example `$(SRCROOT)/../.env`) on your app target.

<Tab.Group tabs={['Expo', 'Bare React Native']}>
<Tab.List>
Expand Down Expand Up @@ -294,15 +294,15 @@ If you aren't using the Expo config plugin, wire up the uploads manually.

#### iOS

In Xcode, add a **Run Script** build phase to your main app target and place it **last** so it runs after the dSYM bundle is produced. The `upload-symbols.sh` script ships with the transitive `posthog-ios` dependency. Use the script path that matches your [iOS dependency path](/docs/libraries/react-native#choose-an-ios-dependency-path-for-the-native-plugin).
In Xcode, add a **Run Script** build phase to your main app target and place it **last** so it runs after the dSYM bundle is produced. The `upload-symbols.sh` script ships with the transitive `posthog-ios` dependency. Use the script path that matches your [iOS dependency path](/docs/libraries/react-native#choose-an-ios-dependency-path-for-the-native-plugin). With `@posthog/react-native-plugin` 3.0 and later, use the **SwiftPM** path on every iOS dependency path, including CocoaPods. The **CocoaPods** path applies only to plugin 2.x on CocoaPods.

<MultiLanguage>

```bash file=CocoaPods
"${PODS_ROOT}/PostHog/build-tools/upload-symbols.sh"
```

```bash file=Swift Package Manager
```bash file=SwiftPM
"${BUILD_DIR%/Build/*}/SourcePackages/checkouts/posthog-ios/build-tools/upload-symbols.sh"
```

Expand All @@ -321,7 +321,7 @@ To also upload native source files for source-code context (iOS only), prefix th
POSTHOG_INCLUDE_SOURCE=1 "${PODS_ROOT}/PostHog/build-tools/upload-symbols.sh"
```

```bash file=Swift Package Manager
```bash file=SwiftPM
POSTHOG_INCLUDE_SOURCE=1 "${BUILD_DIR%/Build/*}/SourcePackages/checkouts/posthog-ios/build-tools/upload-symbols.sh"
```

Expand Down
Loading
Loading