Skip to content

docs(react-native): document per-scheme sentry.properties on iOS #17396

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
antonis merged 1 commit into from
Apr 21, 2026
Merged

docs(react-native): document per-scheme sentry.properties on iOS #17396

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
25 changes: 25 additions & 0 deletions docs/platforms/react-native/troubleshooting/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -70,6 +70,31 @@ If you're using an older version of the SDK (version `3.2.12` or lower) or `sent
../node_modules/react-native/scripts/react-native-xcode.sh --force-foreground
```

## Different `sentry.properties` Per Scheme or Build Configuration (iOS)

Unlike Android's `flavorAware` option, iOS doesn't auto-select a `sentry.properties` file per configuration. If your app has multiple schemes or build configurations that need to upload to different Sentry projects, select the file at build time with a User-Defined Build Setting.

1. In Xcode, open the **Build Settings** tab, click **+**, and choose **Add User-Defined Setting**. Name it `SENTRY_PROPERTIES_FILE`.
2. Expand the new setting and set a value per configuration, for example `sentry-staging.properties` for `Staging` and `sentry-production.properties` for `Production`.
3. Reference the setting from the Sentry build phases by exporting `SENTRY_PROPERTIES`:

```bash {filename:Bundle React Native code and images}
export SENTRY_PROPERTIES="$SENTRY_PROPERTIES_FILE"

WITH_ENVIRONMENT="../node_modules/react-native/scripts/xcode/with-environment.sh"
SENTRY_XCODE="../node_modules/@sentry/react-native/scripts/sentry-xcode.sh"

/bin/sh -c "$WITH_ENVIRONMENT $SENTRY_XCODE"
```

```bash {filename:Upload Debug Symbols to Sentry}
export SENTRY_PROPERTIES="$SENTRY_PROPERTIES_FILE"

/bin/sh ../node_modules/@sentry/react-native/scripts/sentry-xcode-debug-files.sh
```

Xcode substitutes the User-Defined Build Setting for the active configuration, so each build uploads to the matching Sentry project. The same pattern works for `SENTRY_RELEASE`, `SENTRY_DIST`, and other per-build environment variables.

## Release Health

If your release health statistics are being attributed to the wrong release, confirm that you [pass the `release` and `dist` to the `init` call](/platforms/react-native/configuration/releases/#bind-the-version).
Expand Down
Loading