Manual Configuration
Learn about manual configuration for iOS and Android.
If you can't (or prefer not to) run the automatic setup, use the instructions below to configure your application.
Install the @sentry/react-native package:
npm install @sentry/react-native --save
For iOS, the Sentry SDK wraps the React Native bundle process to upload source maps automatically. The SDK also adds a new Xcode Build Phase to upload debug symbols to ensure you get readable stack traces for your native crashes.
The SDK needs access to certain information about the device and the application for its essential functionality. Some of the APIs required for this are considered privacy-relevant. Add the privacy manifest to your Xcode project to ensure your app is compliant with Apple's guidelines. Read the Apple Privacy Manifest guide for more info on how to add records required for the Sentry SDKs.
Add a sentry.properties file to your ios directory.
ios/sentry.propertiesdefaults.url=https://sentry.io/
defaults.org=example-org
defaults.project=example-project
auth.token=sntrys_YOUR_TOKEN_HERE
We modify the React Native build phase (“Bundle React Native code and images”) slightly from this:
Bundle React Native code and imagesset -e
WITH_ENVIRONMENT="../node_modules/react-native/scripts/xcode/with-environment.sh"
REACT_NATIVE_XCODE="../node_modules/react-native/scripts/react-native-xcode.sh"
/bin/sh -c "$WITH_ENVIRONMENT $REACT_NATIVE_XCODE"
To this:
Bundle React Native code and imagesset -e
WITH_ENVIRONMENT="../node_modules/react-native/scripts/xcode/with-environment.sh"
REACT_NATIVE_XCODE="../node_modules/react-native/scripts/react-native-xcode.sh"
SENTRY_XCODE="../node_modules/@sentry/react-native/scripts/sentry-xcode.sh"
BUNDLE_REACT_NATIVE="/bin/sh $SENTRY_XCODE $REACT_NATIVE_XCODE"
# RN 0.69+
/bin/sh -c "$WITH_ENVIRONMENT \"$BUNDLE_REACT_NATIVE\""
# RN 0.46 – 0.68
# /bin/sh -c "$BUNDLE_REACT_NATIVE"
To change the default behavior, pass the following environment variables in .xcode.env or in the Build Phase script:
.xcode.envexport SENTRY_PROPERTIES=path/to/sentry.properties
export SENTRY_DISABLE_AUTO_UPLOAD=true # Temporarily disable source map upload
export AUTO_RELEASE=true # Automatically detect release from Xcode project
export SENTRY_CLI_EXECUTABLE="path/to/@sentry/cli/bin/sentry-cli"
export SENTRY_CLI_EXTRA_ARGS="--extra --flags" # Extra arguments for sentry-cli in all build phases
export SENTRY_CLI_RN_XCODE_EXTRA_ARGS="--extra --flags"
export SOURCE_MAP_PATH="path/to/source-maps" # From where collect-modules should read modules
export SENTRY_COLLECT_MODULES="path/to/collect-modules.sh"
export MODULES_PATHS="../node_modules,../my-custom-module"
By default, uploading of source maps for debug simulator builds is disabled for speed reasons. If you want to generate source maps for debug builds, you can pass --allow-fetch as a parameter to SENTRY_CLI_RN_XCODE_EXTRA_ARGS in the above mentioned script.
To upload debug symbols to Sentry, create a new Run Script build phase using the following script:
Upload Debug Symbols to Sentry/bin/sh ../node_modules/@sentry/react-native/scripts/sentry-xcode-debug-files.sh
To change the default behavior, you can pass the following environment variables in .xcode.env or in the Build Phase script:
.xcode.envexport SENTRY_PROPERTIES=path/to/sentry.properties
export SENTRY_DISABLE_AUTO_UPLOAD=true # Temporarily disable debug symbols upload
export SENTRY_INCLUDE_NATIVE_SOURCES=true # Upload native iOS sources
export SENTRY_CLI_EXECUTABLE="paht/to/@sentry/cli/bin/sentry-cli"
export SENTRY_CLI_EXTRA_ARGS="--extra --flags" # Extra arguments for sentry-cli in all build phases
export SENTRY_CLI_DEBUG_FILES_UPLOAD_EXTRA_ARGS="--extra --flags"
For more information about what options to use in SENTRY_CLI_DEBUG_FILES_UPLOAD_EXTRA_ARGS visit the Sentry CLI Apple Debug Symbols documentation.
If you're using nvm or Volta, Xcode may have trouble locating the default node binary. The suggested workaround in this troubleshooting example can help.
For Android, we hook into Gradle for the source map build process. When you run npx @sentry/wizard@latest -i reactNative, the Gradle files are automatically updated. If you can't or don't want to do that, you can follow the steps below to update the files.
Add a sentry.properties file to your android directory.
android/sentry.propertiesdefaults.url=https://sentry.io/
defaults.org=example-org
defaults.project=example-project
auth.token=sntrys_YOUR_TOKEN_HERE
We enable the Gradle integration in your android/app/build.gradle file by adding the following line before the android options:
android/app/build.gradleapply from: "../../node_modules/@sentry/react-native/sentry.gradle"
To change the default behavior, you can pass the following Sentry Gradle Integration options and environmental variables:
export SENTRY_PROPERTIES=path/to/sentry.properties
export SENTRY_DISABLE_AUTO_UPLOAD=true # Temporarily disable source maps upload
export SENTRY_DIST=1234
export SENTRY_RELEASE=app@1.0.0
You can enable native symbol upload and other features by adding the Sentry Android Gradle Plugin (AGP) dependency to android/build.gradle.
android/build.gradlebuildscript {
dependencies {
// Other dependencies ...
classpath("io.sentry:sentry-android-gradle-plugin:4.13.0")
}
}
You can configure the plugin options in android/app/build.gradle, as shown below:
android/app/build.gradleapply plugin: "io.sentry.android.gradle"
sentry {
// Enables or disables the automatic configuration of Native Symbols
// for Sentry. This executes sentry-cli automatically so
// you don't need to do it manually.
// Default is disabled.
uploadNativeSymbols = true
// Enables or disables the automatic upload of the app's native source code to Sentry.
// This executes sentry-cli with the --include-sources param automatically so
// you don't need to do it manually.
// This option has an effect only when [uploadNativeSymbols] is enabled.
// Default is disabled.
includeNativeSources = true
// `@sentry/react-native` ships with compatible `sentry-android`
// This option would install the latest version that ships with the SDK or SAGP (Sentry Android Gradle Plugin)
// which might be incompatible with the React Native SDK
// Enable auto-installation of Sentry components (sentry-android SDK and okhttp, timber and fragment integrations).
// Default is enabled.
autoInstallation {
enabled = false
}
}
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").