Skip to main content
Browser monitoring ist ein Beta-Feature von AppSignal 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.
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 generieren lassen oder die folgenden Beispiele nutzen. Wenn Sie Ihre Anwendung noch nicht zu AppSignal hinzugefügt haben, folgen Sie zuerst dem Installationsleitfaden.

Ihren Front-end API key finden

Den Front-end API key finden Sie unter Front-end error monitoring in den Einstellungen Ihrer Anwendung. Er steht auf der Seite „Push & deploy“. 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.

Das Snippet in AppSignal generieren

Der Browser SDK install flow 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: 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. Beide Versionen zeigen außerdem, wie Sie einen selbst abgefangenen Fehler melden. Die React-Version enthält eine Error Boundary für Render-Fehler.

Das Paket installieren

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:
Committen Sie Ihre Lockfile, und prüfen Sie das Snippet, wenn Sie während der Beta aktualisieren.

Das SDK initialisieren

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 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. Ersetzen Sie die CSS-Selektoren, Tags und das Router-Beispiel durch Werte aus Ihrer Anwendung.
1. Initialisieren Sie AppSignal in appsignal.js.
appsignal.js
Importieren Sie diese Datei als Erstes in Ihrem Einstiegspunkt:
main.js
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.
router.js
3. Fügen Sie nach der Anmeldung Tags hinzu. Verwenden Sie Werte des angemeldeten Nutzers oder Kontos. Rufen Sie beim Abmelden clearTags() auf, um gespeicherte Tags zu löschen.
account.js
4. Melden Sie selbst abgefangene Fehler. Ersetzen Sie save() durch Ihre eigene Operation.
save.js
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:
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.

Installation ohne Bundler

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:
Ersetzen Sie die Version in der URL, wenn Sie aktualisieren. Eine feste Version verhindert eine unerwartete Änderung des SDK auf Ihrer Website.

Die aktuelle Route melden

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.

Die Installation überprüfen

  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:
    JavaScript
    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.

Content Security Policy

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:

CDN-gehostete Assets

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:

Deinstallation

  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.
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.