From 8c346203ea1e4840ce0e5040f93858d9f7c2cbe8 Mon Sep 17 00:00:00 2001
From: Francesco Novy <francesco.novy@sentry.io>
Date: Mon, 27 May 2024 11:45:33 +0200
Subject: [PATCH] feat(js): Update docs for custom integrations (#10150)

---------

Co-authored-by: Andrei <168741329+andreiborza@users.noreply.github.com>
---
 .../configuration/integrations/custom.mdx     | 105 +++++++++++++++---
 1 file changed, 89 insertions(+), 16 deletions(-)

diff --git a/docs/platforms/javascript/common/configuration/integrations/custom.mdx b/docs/platforms/javascript/common/configuration/integrations/custom.mdx
index fc5ed3a7be8d5..121aa54046e5d 100644
--- a/docs/platforms/javascript/common/configuration/integrations/custom.mdx
+++ b/docs/platforms/javascript/common/configuration/integrations/custom.mdx
@@ -14,8 +14,9 @@ A custom integration can be created and added to the SDK as follows:
 function myAwesomeIntegration() {
   return {
     name: "MyAwesomeIntegration",
-    setupOnce() {
+    setup(client) {
       // Do something when the SDK is initialized
+      // The client that is being setup is passed to the hook
     },
   };
 }
@@ -26,22 +27,94 @@ Sentry.init({
 });
 ```
 
-The JavaScript Core Package (`@sentry/core`) also exports a helper function called `defineIntegration` to help with type-safety:
+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:
 
-```typescript
-import { defineIntegration } from "@sentry/core";
+### `setup`
 
-const myAwesomeIntegration = defineIntegration(() => {
-  return {
-    name: "MyAwesomeIntegration",
-    setupOnce() {
-      // Do something when the SDK is initialized
-    },
-  };
-});
+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 on initialization.
 
-Sentry.init({
-  // ...
-  integrations: [myAwesomeIntegration()],
-});
+```javascript
+const integration = {
+  name: "MyAwesomeIntegration",
+  setup(client) {
+    setupCustomSentryListener(client);
+  },
+};
+```
+
+### `processEvent`
+
+This hook can be used to modify events before they are 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, and the client that is 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 is called before the event is passed to any other `processEvent` hook. It can be used in places where the order of processing is important.
+
+In most cases, you should just use `processEvent`. Only use `preprocessEvent` if you need to ensure that your hook is called before any other `processEvent` hook.
+
+Similar to `processEvent`, this hooks receives the event, hint, and client as arguments. However, this hook does not allow to return a modified event or `null` to drop the event - instead, 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 is only run once, even if the SDK is re-initialized. It does not receive any arguments.
+You should probably not use this, but use `setup` instead. The only reason to use `setupOnce` is e.g. 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`
+
+This hook is triggered after `setupOnce()` and `setup()` have been called for all integrations.
+You can use it if it is important that all other integrations have been run before.
+
+In most cases, you should not need to use this hook, and should use `setup` instead.
+
+The hook receives the `client` that is being set up as the first argument.
+
+```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);
+  },
+};
 ```