Unclear documentation about `autoInitializeNativeSdk`

[bitcrumb]

Core or SDK?

Core Sentry product

Which part? Which one?

React Native

Description

I find the documentation on https://docs.sentry.io/platforms/react-native/manual-setup/native-init/ lacking. I am looking into setting up the native iOS/Android SDK manually, but I run into questions which are not answered decisively by the current documentation:

• What if you don't set autoInitializeNativeSdk to false? Is it a problem if you both initialize natively and at the JS side?
• It is unclear if calling Sentry.init() is still required when already manually starting the SDK on the native side? I assume so, since the documentation mentioned setting autoInitializeNativeSdk? But why would you still need to call this anyway if it is already initialized at the native side?
• Does this imply that you can still pass on extra options to the JS invocation of Sentry.init even if you already passed options on the native side? Is this allowed? Will these be merged?
• Similarly, it is unclear if calling Sentry.init({ dns: '...' }) with a dns is required or not since the dns is already provide via native initialisation?

Suggested Solution

Extend the documentation to clearly shed light on the above issues.

[getsantry[bot]]

Assigning to @getsentry/support for routing ⏲️

[getsantry[bot]]

Routing to @getsentry/product-owners-sdks-mobile for triage ⏲️

[kahest]

Hey @bitcrumb, thanks for writing in and your detailled feedback - we'll look into how we can best address the questions you have.

[bitcrumb]

@kahest Any chance I can already have some quick feedback on this?

[krystofwoldrich]

@bitcrumb Thank you for the message, we will update the docs, but before we do that here are answers to your questions.

What if you don't set autoInitializeNativeSdk to false? Is it a problem if you both initialize natively and at the JS side?

If you don't set autoInitializeNativeSdk in the JS to false, the JS SDK will initialize the native iOS/Android SDK with the options from JS. If you want to initialize iOS/Android SDK yourself then this option should be set to true otherwise the iOS/Android is initialized twice which might lead to unexpected behavior. At a minimum, the native options will be overwritten by the JS.

It is unclear if calling Sentry.init() is still required when already manually starting the SDK on the native side? I assume so, since the documentation mentioned setting autoInitializeNativeSdk? But why would you still need to call this anyway if it is already initialized at the native side?

You still have to call Sentry.init() in JS when initializing the native SDKs yourself. If the JS SDK is not initialized, only native errors with native stack traces will be reported. To receive JS errors and use Sentry.captureException() in JS the SDK has to be initialized in JS too.

Does this imply that you can still pass on extra options to the JS invocation of Sentry.init even if you already passed options on the native side? Is this allowed? Will these be merged?

If autoInitializeNativeSdk set to false you can provide different options to JS and native SDKs, these options won't be merged.

Similarly, it is unclear if calling Sentry.init({dsn: '...' }) with a dsn is required or not since the dsn is already provide via native initialisation?

Yes, the dsn is required in both JS and native SDKs. You can for example use three Sentry projects one for JS errors, one for iOS, and one Android, so each SDK will be initialized with a different DSN. But note we recommend using one project if your use case doesn't require separate projects.

I hope the answers clear the SDKs setup for you, if not, please, feel free to follow up here.

[bitcrumb]

@krystofwoldrich Thanks for answering!

Maybe a follow-up question, with the context that I both initialize the SDK via the native side AND the JS side. And that I set the autoInitializeNativeSdk option to false.

What happens if I set enableAutoPerformanceTracing and tracesSampleRate both via the native option set and the JS option set.

Is it correct (given your answer above) that the options set at the JS side will not override the same options that were set natively? And that these options just are applied to different tracing mechanisms (native vs. JS)?

And related question: if I only initialize the Sentry SDK through JS (with autoInitializeNativeSdk (implicitly) being true), both native & JS tracing will use the same option values?

Sorry if this seems like a silly question, but I really want to make sure that I grasp all the little details. Feels like I'm having difficulties assessing which options apply to JS or native or both?

[krystofwoldrich]

@bitcrumb Good question, absolutely not silly.

If you enableAutoPerformanceTracing and tracesSampleRate both in JS and native you will get duplicate Transactions in Sentry. Navigation between screens will be captured both in JS and native independently.

When initializing the SDK from JS, autoInitializeNativeSdk:true, most of the options are passed as is, but some like tracesSampleRate are not. We want to avoid duplicate data therefore we don't create any transaction in the native SDK by default.

Besides the mentioned, we make other changes, which you can see in https://github.com/getsentry/sentry-react-native/blob/e64a66fe09c19d131d989cb8f49df365df6eb17f/android/src/main/java/io/sentry/react/RNSentryModuleImpl.java#L114 and https://github.com/getsentry/sentry-react-native/blob/e64a66fe09c19d131d989cb8f49df365df6eb17f/ios/RNSentry.mm#L65