Add React Native V6 Changes (#11320)

Co-authored-by: Liza Mock <[email protected]>
Co-authored-by: LucasZF <[email protected]>
Co-authored-by: Antonis Lilis <[email protected]>

Author: 4 people

docs/platforms/react-native/enriching-events/context/index.mdx

@@ -89,6 +89,7 @@ Sentry.captureException(new Error("something went wrong"), () => scope);
 
 Context is held in the current scope and thus is cleared when the scope is removed ("popped"). You can push and pop your own scopes to apply context data to a specific code block or function.
 
+
 Sentry supports two different ways for unsetting context:
 
 1. Modifying, overwriting or clearing values on the current scope.
@@ -100,10 +101,10 @@ With the following snippet, the `user` context will be updated for all future ev
 Sentry.setUser(someUser);
 ```
 
-If you want to remove data from the current scope, you can call:
+If you want to remove all data from the current scope, you can call:
 
 ```javascript
-Sentry.configureScope((scope) => scope.clear());
+Sentry.getCurrentScope().clear();
 ```
 
 The following will only configure the `user` context for the error captured inside the `withScope` callback. The context will be automatically restored to the previous state afterwards:

docs/platforms/react-native/enriching-events/scopes/index.mdx

@@ -1,78 +1,143 @@
 ---
-title: Scopes and Hubs
+title: Scopes
 description: "SDKs will typically automatically manage the scopes for you in the framework integrations. Learn what a scope is and how you can use it to your advantage."
 ---
 
 When an event is captured and sent to Sentry, SDKs will merge that event data with extra
 information from the current scope. SDKs will typically automatically manage the scopes
 for you in the framework integrations and you don't need to think about them. However,
-you should know what a scope is and how you can use it for your advantage.
+you should know what a scope is and how you can use it to your advantage.
 
-## What's a Scope, What's a Hub
+## What's a Scope?
 
-You can think of the hub as the central point that our SDKs use to route an
-event to Sentry. When you call `init()` a hub is created and a client and a
-blank scope are created on it. That hub is then associated with the current
-thread and will internally hold a stack of scopes.
-
-The scope will hold useful information that should be sent along with the
-event. For instance [contexts](../context/) or
+Scopes hold useful information that gets sent along with the
+event. For instance, [contexts](../context/) and
 [breadcrumbs](../breadcrumbs/) are stored on
-the scope. When a scope is pushed, it inherits all data from the parent scope
-and when it pops all modifications are reverted.
+the scope. When a scope is forked, it inherits all data from its parent scope.
+
+The default SDK integrations will fork scopes intelligently. For
+instance, web framework integrations will fork scopes around your
+routes or request handlers.
+
+## How Scopes Work
+
+Scopes are basically stacks of data that are attached to events. When an event is captured, the SDK will merge the data from the active scopes into the event. This allows you to attach data to events that is relevant to the context in which the event was captured.
+
+A scope is generally valid inside of a callback or an execution context. This means that multiple parts of your application may have different scopes active at the same time. For instance, a web server might handle multiple requests at the same time, and each request may have different scope data to apply to its events.
+
+## Different Kinds of Scopes
+
+The Sentry SDK has three different kinds of scopes:
+
+- [Global scope](#global-scope)
+- [Isolation scope](#isolation-scope)
+- [Current scope](#current-scope)
+
+### Global Scope
+
+The global scope is applied to _all_ events, no matter where they originate. You can use it to store data that should apply to all events, such as environmental information.
+
+You can access the global scope via `Sentry.getGlobalScope()`.
+
+Note, that the global scope can only be used to write data, not to capture events. Events can only be captured on the current scope (for example, `getCurrentScope().captureException()` and similar APIs).
+
+### Isolation Scope
+
+The isolation scope is used to isolate events from each other. For example, each request in a web server might get its own isolation scope, so that events from one request don't interfere with events from another. In most cases, you'll want to put data that should be applied to your events on the isolation scope. This is why all `Sentry.setXXX` methods, like `Sentry.setTag()` will write data onto the currently active isolation scope. A classic example of data that belongs on the isolation scope is user data, where each request may have a different user, so you'd want to make sure that the user is set on the isolation scope.
 
-The default SDK integrations will push and pop scopes intelligently. For
-instance web framework integrations will create and destroy scopes around your
-routes or controllers.
+You can access the isolation scope via `Sentry.getIsolationScope()`, but usually you'll just use the `Sentry.setXXX` methods to set data on the currently active isolation scope:
 
-## How the Scope and Hub Work
+```javascript
+Sentry.setTag("my-tag", "my value");
+// Is identical to:
+Sentry.getIsolationScope().setTag("my-tag", "my value");
+```
 
-As you start using an SDK, a scope and hub are automatically created for you out
-of the box. It's unlikely that you'll interact with the hub directly unless you're
-writing an integration or you want to create or destroy scopes. Scopes, on the
-other hand are more user facing. You can call <PlatformIdentifier name="configure-scope" /> at any point in
-time to modify data stored on the scope. This is useful for doing things like
-[modifying the context](../context/).
+<PlatformCategorySection supported={["browser"]}>
+In the browser, the isolation scope is never forked because it's impossible to keep track of where an isolation scope would belong. This is why the isolation scope is effectively global in the browser.
+</PlatformCategorySection>
 
-When you call a global function such as <PlatformIdentifier name="capture-event" /> internally Sentry
-discovers the current hub and asks it to capture an event. Internally the hub will
-then merge the event with the topmost scope's data.
+Note, that the isolation scope can only be used to write data, not to capture events. Events can only be captured on the current scope (for example, `getCurrentScope().captureException()` and similar APIs).
+
+### Current Scope
+
+Current scope is the local scope that's currently active. Unlike the rarely-forked isolation scope, the current scope may be forked more frequently and under the hood. It can be used to store data that should only be applied to specific events. In most cases, you shouldn't access this scope directly, but use `Sentry.withScope` to create a new scope that's only active for a specific part of your code:
+
+```javascript
+Sentry.withScope((scope) => {
+  // scope is the current scope inside of this callback!
+  scope.setTag("my-tag", "my value");
+  // this tag will only be applied to events captured inside of this callback
+  // the following event will have the tag:
+  Sentry.captureException(new Error("my error"));
+});
+// this event will not have the tag:
+Sentry.captureException(new Error("my other error"));
+```
+
+You can access the current scope via `Sentry.getCurrentScope()`, but you should use `Sentry.withScope()` to interact with local scopes in most cases instead.
+
+## How Scope Data is Applied to Events
+
+Before an event (like an error or transaction) is sent to Sentry, the currently active scopes are applied to it.
+
+The global scope is applied first, followed by the isolation scope, and finally the current scope. This means that any data set on the current scope will take precedence over data set on the isolation and global scopes:
+
+```javascript
+Sentry.getGlobalScope().setExtras({
+  shared: "global",
+  global: "data",
+});
+Sentry.getIsolationScope().setExtras({
+  shared: "isolation",
+  isolation: "data",
+});
+Sentry.getCurrentScope().setExtras({
+  shared: "current",
+  current: "data",
+});
+
+Sentry.captureException(new Error("my error"));
+// --> Will have the following extra:
+// { shared: 'current', global: 'data', isolation: 'data', current: 'data' }
+```
 
 ## Configuring the Scope
 
-The most useful operation when working with scopes is the <PlatformIdentifier name="configure-scope" /> function. It can be used to reconfigure the current scope.
+There are two main ways to interact with the scope. You can access the current scope via `Sentry.getCurrentScope()` and use setters on the resulting scope, or you can use global methods like `Sentry.setTag()` directly, which will set on the respective scope under the hood (this will be the isolation scope).
 
 You'll first need to import the SDK, as usual:
 
 <PlatformContent includePath="enriching-events/import" />
 
 You can, for instance, add custom tags or inform Sentry about the currently authenticated user.
 
-<PlatformContent includePath="enriching-events/scopes/configure-scope" />
-
-You can also apply this configuration when unsetting a user at logout:
-
-<PlatformContent includePath="enriching-events/unset-user" />
+```javascript
+/// Usually, you don't want to write on the current scope, so use with care!
+const scope = Sentry.getCurrentScope();
+scope.setTag("my-tag", "my value");
+scope.setUser({
+  id: 42,
+  email: "[email protected]",
+});
+
+// Or use the global methods (which will set data on the isolation scope):
+Sentry.setTag("my-tag", "my value");
+Sentry.setUser({
+  id: 42,
+  email: "[email protected]",
+});
+```
 
 To learn what useful information can be associated with scopes see
-[the context documentation](../context/).
+[context](../context/), [tags](../tags), [users](../identify-user) and [breadcrumbs](../breadcrumbs/).
 
-## Local Scopes
-
-We also support pushing and configuring a scope within a single call. This is typically
-called <PlatformIdentifier name="with-scope" />, <PlatformIdentifier name="push-scope" /> or implemented as a function parameter on the capture methods, depending on the SDK. It's very helpful if
-you only want to send data for one specific event.
-
-### Using <PlatformIdentifier name="with-scope" />
+## Using `withScope`
 
 In the following example we use <PlatformIdentifier name="with-scope" /> to attach a `level` and a `tag` to only one specific error:
 
 <PlatformContent includePath="enriching-events/scopes/with-scope" />
 
-While this example looks similar to <PlatformIdentifier name="configure-scope" />, it is actually very different.
-Calls to <PlatformIdentifier name="configure-scope" /> change the current active scope; all successive calls to <PlatformIdentifier name="configure-scope" /> will maintain previously set changes unless they are explicitly unset.
-
-On the other hand, <PlatformIdentifier name="with-scope" /> creates a clone of the current scope, and the changes
-made will stay isolated within the <PlatformIdentifier name="with-scope" /> callback function. This allows you to
+The scope inside the `withScope()` callback is only valid inside of the callback. Once the callback ends, the scope will be removed and will no longer apply. The inner scope is only applied to events that are captured inside of the callback. `withScope()` will clone (or fork) the current scope, so the current scope won't be modified. This allows you to
 more easily isolate pieces of context information to specific locations in your code or
 even call <PlatformIdentifier name="clear" /> to briefly remove all context information.

docs/platforms/react-native/enriching-events/transaction-name/index.mdx

@@ -22,10 +22,14 @@ A lot of our framework integrations already set a transaction name, though you c
 
 You'll first need to import the SDK, as usual:
 
-<PlatformContent includePath="enriching-events/import" />
+```javascript
+import * as Sentry from "@sentry/react-native";
+```
 
 To override the name of the currently running transaction:
 
-<PlatformContent includePath="enriching-events/set-transaction-name" />
+```javascript
+Sentry.getCurrentScope().setTransactionName("UserListView");
+```
 
 Please refer to [the tracing documentation](../../tracing/) for how to start and stop transactions.

docs/platforms/react-native/index.mdx

@@ -38,7 +38,7 @@ Sentry captures data by using an SDK within your application's runtime. These ar
 To install, run `@sentry/wizard`:
 
 ```bash {tabTitle:npm}
-npx @sentry/wizard@latest -s -i reactNative
+npx @sentry/wizard@latest -i reactNative
 ```
 
 [Sentry Wizard](https://github.com/getsentry/sentry-wizard) will patch your project accordingly, though you can [set up manually](/platforms/react-native/manual-setup/manual-setup/) if you prefer. You only need to patch the project once. Then you can add the patched files to your version control system.
@@ -65,19 +65,17 @@ If you're using Expo, [read our docs](/platforms/react-native/manual-setup/expo/
 To capture all errors, initialize the Sentry React Native SDK as soon as possible.
 
 
-```javascript {filename:App.js} {"onboardingOptions": {"performance": "5-7", "profiling": "8-12"}}
+```javascript {filename:App.js} {"onboardingOptions": {"performance": "5-7", "profiling": "8-10"}}
 import * as Sentry from "@sentry/react-native";
 
 Sentry.init({
   dsn: "___PUBLIC_DSN___",
   // Set tracesSampleRate to 1.0 to capture 100% of transactions for tracing.
   // We recommend adjusting this value in production.
   tracesSampleRate: 1.0,
-  _experiments: {
-    // profilesSampleRate is relative to tracesSampleRate.
-    // Here, we'll capture profiles for 100% of transactions.
-    profilesSampleRate: 1.0,
-  },
+  // profilesSampleRate is relative to tracesSampleRate.
+  // Here, we'll capture profiles for 100% of transactions.
+  profilesSampleRate: 1.0,
 });
 ```
 

docs/platforms/react-native/integrations/custom.mdx

@@ -1,7 +1,115 @@
 ---
 title: Custom Integrations
+sidebar_order: 200
 description: "Learn how to enable a custom integration."
-sidebar_order: 3
 ---
 
-<Include name="platforms/configuration/integrations/custom.mdx" />
+In addition to the integrations that come with the SDK, you can also write custom integrations.
+
+Custom integration must conform to the [Integration interface](https://github.com/getsentry/sentry-javascript/blob/master/packages/types/src/integration.ts).
+
+A custom integration can be created and added to the SDK as follows:
+
+```javascript
+function myAwesomeIntegration() {
+  return {
+    name: "MyAwesomeIntegration",
+    setup(client) {
+      // Do something when the SDK is initialized
+      // The client that is being setup is passed to the hook
+    },
+  };
+}
+
+Sentry.init({
+  // ...
+  integrations: [myAwesomeIntegration()],
+});
+```
+
+All hooks on an integration are optional. The only required field is the `name`. You can use one or multiple of the following hooks in a custom integration:
+
+### `setup`
+
+The `setup` hook is called when the SDK is initialized. It receives the client instance as an argument.
+You should use this if you want to run some code upon initialization.
+
+```javascript
+const integration = {
+  name: "MyAwesomeIntegration",
+  setup(client) {
+    setupCustomSentryListener(client);
+  },
+};
+```
+
+### `processEvent`
+
+This hook can be used to modify events before they're sent to Sentry. It receives the event as an argument and should return the modified event. The hook also receives a hint object that may hold additional event metadata, as well as the client that's sending the event. You can also return `null` to drop the event from being sent.
+
+```javascript
+const integration = {
+  name: "MyAwesomeIntegration",
+  processEvent(event, hint, client) {
+    event.extra = {
+      ...event.extra,
+      myCustomTag: "value",
+    };
+    // Return the modified event,
+    // or return `null` to drop the event
+    return event;
+  },
+};
+```
+
+You can also return a promise that resolves with an event or `null`. However, this is not recommended and should be avoided wherever possible, because it can delay event sending.
+
+### `preprocessEvent`
+
+This hook is similar to `processEvent`, but it's called before the event is passed to any other `processEvent` hook. It can be used in places where the order of processing is important.
+
+You can use `processEvent` for most cases, but only when you need to ensure that your hook is called before any other `processEvent` hook use `preprocessEvent`.
+
+Similar to `processEvent`, this hook receives the event, hint, and client as arguments. However, this hook won't allow the return of a modified event or `null` to drop the event. You can only mutate the passed in event in this hook:
+
+```javascript
+const integration = {
+  name: "MyAwesomeIntegration",
+  preprocessEvent(event, hint, client) {
+    event.extra = {
+      ...event.extra,
+      myCustomTag: "value",
+    };
+    // Nothing to return, just mutate the event
+  },
+};
+```
+
+### `setupOnce`
+
+This hook is similar to `setup`, but it's only run once, even if the SDK is re-initialized. It won't receive any arguments. We recommend that you use `setup` instead. The only reason to use `setupOnce` is when you may be calling `Sentry.init()` multiple times and you want to ensure a certain piece of code is only run once.
+
+```javascript
+const integration = {
+  name: "MyAwesomeIntegration",
+  setupOnce() {
+    wrapLibrary();
+  },
+};
+```
+
+### `afterAllSetup`
+
+While we recommend that you use the `setup` hook in most cases, `afterAllSetup` can be used to make sure that all other integrations have been run. This hook receives the `client` that is being set up as the first argument and is triggered after `setupOnce()` and `setup()` have been called for all integrations. 
+
+
+```javascript
+const integration = {
+  name: "MyAwesomeIntegration",
+  afterAllSetup(client) {
+    // We can be sure that all other integrations
+    // have run their `setup` and `setupOnce` hooks now
+    startSomeThing(client);
+  },
+};
+```