> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appsignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AppSignal für Browser installieren

<Note>
  Browser monitoring ist ein Beta-Feature von [AppSignal Labs](/labs). Das Paket
  `@appsignal/browser` wird unter dem `beta`-Tag auf npm veröffentlicht, und
  seine Konfiguration und API können sich zwischen Beta-Releases noch ändern.
  Teilen Sie Ihr Feedback in unserer
  [Discord-Community](https://discord.gg/EjF6ykYx63).
</Note>

Mit dieser Anleitung richten Sie in Ihrer Anwendung Fehlerverfolgung und Web Vitals für den Browser ein. Die Beispiele für Plain JS und React behandeln außerdem verteiltes Tracing, Fehlerfilterung, Maskierung und Tags.

Sie können den Code für Ihre Anwendung im [Browser SDK install flow](https://appsignal.com/redirect-to/organization?to=sites/new/browser) generieren lassen oder die folgenden Beispiele nutzen. Wenn Sie Ihre Anwendung noch nicht zu AppSignal hinzugefügt haben, folgen Sie zuerst dem [Installationsleitfaden](/guides/new-application).

<h2 id="find-your-front-end-api-key">
  Ihren Front-end API key finden
</h2>

Den **Front-end API key** finden Sie unter **Front-end error monitoring** in den Einstellungen Ihrer Anwendung. Er steht auf der Seite [„Push & deploy“](https://appsignal.com/redirect-to/app?to=api_keys). Verwenden Sie den Schlüssel für die Anwendung und Umgebung, die Sie überwachen möchten. Dieser Schlüssel ist dafür vorgesehen, in Browser-Code eingebunden zu werden. Er unterscheidet sich von den Push API keys, die Back-end-Integrationen verwenden.

Der install flow trägt Ihren Schlüssel bereits in den generierten Code ein. Ersetzen Sie in den Beispielen unten `<YOUR_FRONTEND_API_KEY>` durch Ihren eigenen Schlüssel.

<h2 id="generate-the-snippet-in-appsignal">
  Das Snippet in AppSignal generieren
</h2>

Der [Browser SDK install flow](https://appsignal.com/redirect-to/organization?to=sites/new/browser) lässt Sie zwischen **Plain JS** und **React** wählen und bestimmen, welche Funktionen enthalten sein sollen. Standardmäßig ist **Route template** ausgewählt. Die vollständigen Beispiele unten enthalten alle Optionen:

| Optionen | Was in Ihr Snippet aufgenommen wird |
| - | - |
| Route template | `setRouteTemplate()` wird bei jedem Routenwechsel ausgeführt, sodass `/users/42` als `/users/:id` gemeldet werden kann. |
| Distributed tracing | Fügt `tracePropagationTargets` hinzu, sodass passende API-Anfragen einen `traceparent`-Header erhalten. Ersetzen Sie den Beispiel-Host durch Ihren eigenen. Dies konfiguriert nur den Browser; der empfangende API-Service benötigt außerdem [Tracing-Instrumentierung](/browser/distributed-tracing#before-you-start). |
| Error filtering | `beforeError` verwirft Fehler, die den Beispielmustern für Browser und Erweiterungen entsprechen. Passen Sie die Muster an Ihre Anwendung an. |
| Error tags | `setTags()` fügt Fehlern nach der Anmeldung Werte wie einen Plan oder Mandanten hinzu. |
| Sensitive data masking | `privacy.dom` maskiert Text oder schließt Click-Breadcrumbs für ausgewählte Elemente aus. Ersetzen Sie die Beispiel-CSS-Selektoren durch Ihre eigenen. |

Der install flow generiert Browser-SDK-Code. Die Auswahl von **Distributed tracing** instrumentiert Ihren API-Service nicht. Um dessen Spans neben einem Browser-Request-Fehler zu sehen, folgen Sie zusätzlich dem [Back-end-Setup](/browser/distributed-tracing#before-you-start).

Beide Versionen zeigen außerdem, wie Sie einen selbst abgefangenen Fehler melden. Die React-Version enthält eine Error Boundary für Render-Fehler.

<h2 id="install-the-package">
  Das Paket installieren
</h2>

Installieren Sie AppSignal für Browser über den Tag `beta`. Verteiltes Tracing und das Melden fehlgeschlagener Requests erfordern Version 1.0.0-beta.7 oder neuer. Der install flow zeigt derzeit einen Befehl ohne Versionsangabe; verwenden Sie für die Beta-Version einen der folgenden Befehle:

<CodeGroup>
  ```sh npm theme={null}
  npm install @appsignal/browser@beta
  ```

  ```sh yarn theme={null}
  yarn add @appsignal/browser@beta
  ```

  ```sh pnpm theme={null}
  pnpm add @appsignal/browser@beta
  ```
</CodeGroup>

Committen Sie Ihre Lockfile, und prüfen Sie das Snippet, wenn Sie während der Beta aktualisieren.

<h2 id="initialize-the-sdk">
  Das SDK initialisieren
</h2>

Importieren Sie Ihr AppSignal-Setup vor dem Anwendungscode, den Sie überwachen möchten. Ersetzen Sie `process.env.NODE_ENV` und `process.env.APP_REVISION` durch die entsprechenden Werte aus Ihrem Build-System. Setzen Sie `appVersion` auf Ihr Release-Tag oder Ihren Commit-SHA, damit AppSignal Fehler den passenden [Sourcemaps](/browser/error-tracking#sourcemaps) zuordnen kann.

Diese Beispiele enthalten alle Optionen des install flow. Ersetzen Sie `api.example.com/**` durch Ihren API-Host und -Pfad für [verteiltes Tracing](/browser/distributed-tracing#enable-it). Ersetzen Sie die CSS-Selektoren, Tags und das Router-Beispiel durch Werte aus Ihrer Anwendung.

<Tabs>
  <Tab title="Plain JS">
    **1. Initialisieren Sie AppSignal in `appsignal.js`.**

    ```js appsignal.js theme={null}
    import { init } from "@appsignal/browser";

    const IGNORED = [
      /ResizeObserver loop/,
      /^Script error\.?$/,
      /-extension:\/\//,
      /webkit-masked-url/,
    ];

    init({
      key: "<YOUR_FRONTEND_API_KEY>",
      endpoint: "https://appsignal-endpoint.net",
      // Inactive builds send nothing. Replace these with your build values.
      active: process.env.NODE_ENV === "production",
      appVersion: process.env.APP_REVISION,
      // Match your API host and path.
      tracePropagationTargets: ["api.example.com/**"],
      privacy: {
        // Mask text or exclude clicks on these elements.
        dom: { maskText: [".user-email"], blockElement: ["#card-form"] },
      },
      beforeError: (error) => {
        const text = [error.message, error.stack, error.filename].join(" ");
        return IGNORED.some((pattern) => pattern.test(text)) ? null : error;
      },
    });
    ```

    Importieren Sie diese Datei als Erstes in Ihrem Einstiegspunkt:

    ```js main.js theme={null}
    import "./appsignal";

    // Start your application after this import.
    ```

    **2. Melden Sie Routenwechsel aus Ihrem Router.** Ersetzen Sie `router.on` durch den Navigations-Hook Ihres Routers. Melden Sie auch die initiale Route, und melden Sie anschließend bei jeder Navigation deren Vorlage.

    ```js router.js theme={null}
    import { setRouteTemplate } from "@appsignal/browser";

    router.on("navigate", (route) => {
      setRouteTemplate(route.pattern); // "/users/:id", not "/users/42"
    });
    ```

    **3. Fügen Sie nach der Anmeldung Tags hinzu.** Verwenden Sie Werte des angemeldeten Nutzers oder Kontos. Rufen Sie beim Abmelden [`clearTags()`](/browser/configuration#api-reference) auf, um gespeicherte Tags zu löschen.

    ```js account.js theme={null}
    import { setTags } from "@appsignal/browser";

    setTags({ plan: "pro", tenant: "acme" });
    ```

    **4. Melden Sie selbst abgefangene Fehler.** Ersetzen Sie `save()` durch Ihre eigene Operation.

    ```js save.js theme={null}
    import { captureError } from "@appsignal/browser";

    try {
      save();
    } catch (error) {
      captureError(error);
    }
    ```
  </Tab>

  <Tab title="React">
    **1. Initialisieren Sie AppSignal in `appsignal.js`.** Importieren Sie diese Datei, bevor Ihre React-Anwendung startet.

    ```js appsignal.js theme={null}
    import { init } from "@appsignal/browser";

    const IGNORED = [
      /ResizeObserver loop/,
      /^Script error\.?$/,
      /-extension:\/\//,
      /webkit-masked-url/,
    ];

    init({
      key: "<YOUR_FRONTEND_API_KEY>",
      endpoint: "https://appsignal-endpoint.net",
      // Inactive builds send nothing. Replace these with your build values.
      active: process.env.NODE_ENV === "production",
      appVersion: process.env.APP_REVISION,
      // Match your API host and path.
      tracePropagationTargets: ["api.example.com/**"],
      privacy: {
        // Mask text or exclude clicks on these elements.
        dom: { maskText: [".user-email"], blockElement: ["#card-form"] },
      },
      beforeError: (error) => {
        const text = [error.message, error.stack, error.filename].join(" ");
        return IGNORED.some((pattern) => pattern.test(text)) ? null : error;
      },
    });
    ```

    Importieren Sie diese Datei als Erstes in Ihrem Einstiegspunkt:

    ```js main.jsx theme={null}
    import "./appsignal";

    // Start your React application after this import.
    ```

    **2. Melden Sie Routenwechsel.** Rendern Sie `RouteReporter` innerhalb Ihres Routers, und übergeben Sie die aktuelle Routenvorlage als `routePattern`. React-Hooks müssen innerhalb einer Komponente laufen.

    ```jsx RouteReporter.jsx theme={null}
    import { useEffect } from "react";
    import { setRouteTemplate } from "@appsignal/browser";

    export function RouteReporter({ routePattern }) {
      useEffect(() => {
        setRouteTemplate(routePattern); // "/users/:id", not "/users/42"
      }, [routePattern]);

      return null;
    }
    ```

    Siehe die [React-Routenbeispiele](/browser/react#reporting-the-current-route) für React Router und Next.js.

    **3. Fügen Sie nach der Anmeldung Tags hinzu.** Verwenden Sie Werte des angemeldeten Nutzers oder Kontos. Rufen Sie beim Abmelden [`clearTags()`](/browser/configuration#api-reference) auf, um gespeicherte Tags zu löschen.

    ```js account.js theme={null}
    import { setTags } from "@appsignal/browser";

    setTags({ plan: "pro", tenant: "acme" });
    ```

    **4. Fangen Sie Render-Fehler an der Wurzel Ihrer App ab.** Die Boundary meldet Render-Fehler, die den globalen Error-Handler des Browsers nicht erreichen.

    ```jsx AppRoot.jsx theme={null}
    import { captureError } from "@appsignal/browser";
    import { ErrorBoundary } from "@appsignal/browser/react";

    <ErrorBoundary
      captureError={captureError}
      fallback={<p>This page didn't load. Reload to try again.</p>}
    >
      <App />
    </ErrorBoundary>
    ```

    **5. Melden Sie selbst abgefangene Fehler.** Ersetzen Sie `save()` durch Ihre eigene Operation.

    ```js save.js theme={null}
    import { captureError } from "@appsignal/browser";

    try {
      save();
    } catch (error) {
      captureError(error);
    }
    ```
  </Tab>
</Tabs>

**Wenn Sie nur Fehlerverfolgung, Breadcrumbs und Web Vitals benötigen**, können Sie mit einer kleineren `appsignal.js`-Datei beginnen. Ersetzen Sie `<YOUR_APP_REVISION>` durch Ihr Release-Tag oder Ihren Commit-SHA:

<CodeGroup>
  ```js appsignal.js theme={null}
  import { init } from "@appsignal/browser";

  init({
    key: "<YOUR_FRONTEND_API_KEY>",
    endpoint: "https://appsignal-endpoint.net",
    active: process.env.NODE_ENV === "production",
    appVersion: "<YOUR_APP_REVISION>",
  });
  ```
</CodeGroup>

Importieren Sie `appsignal.js` wie oben gezeigt als Erstes in Ihrem Einstiegspunkt. Dieses kleinere Setup fügt Ihren API-Anfragen keine `traceparent`-Header hinzu.

Für jedes Setup gilt: `active: false` stoppt das SDK beim Erfassen und Senden von Daten. `endpoint` verwendet standardmäßig den Origin der aktuellen Seite. Setzen Sie ihn auf `https://appsignal-endpoint.net`, außer Sie leiten AppSignal-Anfragen über Ihre eigene Domain um. Siehe [alle Konfigurationsoptionen](/browser/configuration).

<h2 id="install-without-a-bundler">
  Installation ohne Bundler
</h2>

Wenn Ihre Website JavaScript über `<script>`-Tags lädt und keinen Bundler verwendet, nutzen Sie den UMD-Build. Er stellt das SDK als `AppsignalBrowser` auf `window` bereit:

<CodeGroup>
  ```html HTML theme={null}
  <script src="https://cdn.jsdelivr.net/npm/@appsignal/browser@1.0.0-beta.7/dist/browser.umd.js"></script>
  <script>
    AppsignalBrowser.init({
      key: "<YOUR_FRONTEND_API_KEY>",
      endpoint: "https://appsignal-endpoint.net",
      appVersion: "<YOUR_APP_REVISION>",
    });
  </script>
  ```
</CodeGroup>

Ersetzen Sie die Version in der URL, wenn Sie aktualisieren. Eine feste Version verhindert eine unerwartete Änderung des SDK auf Ihrer Website.

<h2 id="report-the-current-route">
  Die aktuelle Route melden
</h2>

Diesen Schritt benötigen Sie für Single-Page-Anwendungen mit Routen wie `/users/42`. Übergeben Sie die Routenvorlage, zum Beispiel `/users/:id`, bei jeder Navigation Ihres Routers. AppSignal nutzt sie, um Fehler und Web Vitals nach Route zu gruppieren. Die vollständigen Beispiele oben zeigen, wo Sie `setRouteTemplate()` aufrufen.

Wenn Sie keine Routenvorlage setzen, meldet das SDK den aktuellen Seitenpfad. Das bedeutet, dass `/users/42` und `/users/43` als getrennte Fehlergruppen erscheinen können. Informationen zu React Router und Next.js finden Sie unter [React-Routenbeispiele](/browser/react#reporting-the-current-route).

<h2 id="verify-the-installation">
  Die Installation überprüfen
</h2>

1. Führen Sie einen Build mit `active` auf `true` aus. In der Entwicklung können Sie vorübergehend `active: true` verwenden.
2. Öffnen Sie die Seite, und führen Sie diesen Code in der Browser-Konsole aus:

   ```js JavaScript theme={null}
   setTimeout(() => { throw new Error("AppSignal test error"); }, 0);
   ```

   Der Timer sorgt dafür, dass der Fehler den globalen Error-Handler der Seite erreicht. Ein Fehler, der direkt in der Konsole geworfen wird, wird meist von der Konsole selbst behandelt.
3. Öffnen Sie **Browser > Errors** in AppSignal, und suchen Sie nach **AppSignal test error**.

Web Vitals erscheinen, nachdem das SDK sie übermittelt hat, zum Beispiel wenn die Seite ausgeblendet wird oder die Route wechselt. Wenn keine Daten erscheinen, siehe [Fehlerbehebung für Browser](/browser/troubleshooting).

<h2 id="content-security-policy">
  Content Security Policy
</h2>

Wenn Ihre Website eine Content Security Policy verwendet, erlauben Sie den konfigurierten AppSignal-Endpunkt in deren `connect-src`-Direktive. Fügen Sie den Endpunkt zum Beispiel zu Ihren bestehenden erlaubten Quellen hinzu:

<CodeGroup>
  ```http HTTP theme={null}
  Content-Security-Policy: connect-src 'self' https://appsignal-endpoint.net
  ```
</CodeGroup>

<h2 id="assets-hosted-on-a-cdn">
  CDN-gehostete Assets
</h2>

Nutzen Sie diesen Schritt, wenn das JavaScript Ihrer Website von einem anderen Origin geladen wird, zum Beispiel einem CDN. Ohne Cross-Origin-Zugriff meldet der Browser möglicherweise nur `Script error.`, ohne Stacktrace und ohne Zeilennummer. Das SDK verwirft diese nichtssagenden Fehler, weil sie sich nicht auf Ihren Code zurückführen lassen.

Liefern Sie das Skript mit einem `Access-Control-Allow-Origin`-Header aus, der den Origin Ihrer Seite erlaubt, und fügen Sie dem Script-Tag `crossorigin="anonymous"` hinzu:

<CodeGroup>
  ```html HTML theme={null}
  <script src="https://cdn.example.com/bundle.js" crossorigin="anonymous"></script>
  ```

  ```erb Rails theme={null}
  <%= javascript_include_tag "application", :crossorigin => :anonymous %>
  ```
</CodeGroup>

<h2 id="uninstall">
  Deinstallation
</h2>

1. Entfernen Sie den `appsignal.js`-Import und andere `@appsignal/browser`-Aufrufe aus Ihrem Code. Entfernen Sie auch jede `ErrorBoundary`, die Sie aus `@appsignal/browser/react` importiert haben.
2. Entfernen Sie das Paket, und aktualisieren Sie Ihre Lockfile mit `npm uninstall @appsignal/browser`, `yarn remove @appsignal/browser` oder `pnpm remove @appsignal/browser`. Wenn Sie den UMD-Build installiert haben, entfernen Sie stattdessen dessen `<script>`-Tag.
3. Deployen Sie die Änderung. Der neue Build meldet keine Browser-Daten mehr.
4. Wenn diese AppSignal-Anwendung ausschließlich für browser monitoring verwendet wurde, können Sie optional [die Anwendung entfernen](/guides/application/deleting-applications).

Um die Erfassung zu stoppen, ohne zu deinstallieren, rufen Sie `destroy()` auf. Es übermittelt ausstehende Daten und stoppt die Erfassung, bis `init()` erneut läuft, zum Beispiel nach einem Neuladen der Seite.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.