Sentry React Native: Leitfaden zur Integration 2026

Sie haben eine React Native-Anwendung lokal erfolgreich getestet, die QA hat zugestimmt und die Produktion ist nahe. Dann landet die offensichtliche Frage: Was passiert, wenn sie auf einem Gerät des Benutzers kaputt geht?

Ohne Sentry ist die Antwort normalerweise schlecht. Sie erhalten ein Support-Ticket, ein vages Screenshot, vielleicht ein Konsole-Log aus einem Entwickler-Builder, der sich nicht mit der Produktion übereinstimmt. Mit Sentry React Native eingerichtet, erhalten Sie den Fehler, die Stack, die Release, die es verschickt hat, und genug Kontext, um es ohne Vermutungen zu beheben. Der Haken ist, dass Die grundlegende Installation ist das leichte Teil. Die schmerzhaften Teile kommen später: native Integration, Symbolisierung, Source-Maps, Release-Namen und das Festhalten an allem, wenn Ihr Liefermodell Live-Updates beinhaltet.

Die meisten Anleitungen stoppen zu früh. Eine echte Einrichtung muss CI, App-Store-Builds, Android-Releases und JavaScript-Bundles überleben, die nicht immer aus dem Original-Datei stammen.

Tabelle der Inhalte

• Getting Started with the Sentry SDK
  • Anfangen mit Sentry __CAPGO_KEEP_0__
  • Was Sie vor der Installation benötigen
• Der Zauberer ausführen und das Ergebnis überprüfen
  • Konfigurieren Sie Native iOS- und Android-Projekte
  • Was hat sich auf Android geändert
  • Native-Einrichtungen, die Zeit später sparen
• Automatisierung von Releases und Source Maps
  • Warum manuelle Uploads in der Praxis scheitern
  • Ein Release-Prozess, der tatsächlich funktioniert
  • Ein praktisches CI-Skriptmuster
• Leistungsmessung und benutzerdefinierte Ereignisse erfassen
  • Stattdessen eine langsame Anzeige nachspüren
  • Nützliche Kontextinformationen zu Fehlern hinzufügen
• Ihre Integration überprüfen und Fehlerbeheben
  • Sichere Testereignisse auslösen
  • Was im Sentry-UI überprüfen
  • Commone Sentry React Native Fehlerbehebung
• Integrieren mit Live Update Workflows wie Capgo
  • Matching von Release-Identifikatoren mit lebenden Paketen

Erste Schritte mit dem Sentry SDK

Die schnellste Möglichkeit, Sentry React Native in eine neue App zu bringen, ist immer noch der Installations-Assistent. Er handhabt die meisten wiederholten Einstellungen und bringt Sie schnell zu einem funktionierenden Grundlayout. Das ist wichtig, weil die Handarbeit der ersten Installation normalerweise zu kleinen Abweichungen führt, die Sie erst bei der ersten Produktionsstörung bemerken.

Was Sie vor der Installation benötigen

Zuerst benötigen Sie ein normales React Native-Entwicklungsumfeld. Node, ein Paketmanager, Plattform-Tooling für iOS und Android sowie Watchman auf macOS, wenn das bereits Teil Ihres Workflows ist. Sie benötigen auch ein Sentry-Konto und ein Projekt, das für React Native erstellt wurde.

Wenn Sie noch evaluierten, ob React Native die richtige Betriebswahl für Ihr Team ist, gibt es eine React Native-Anleitung für Unternehmen die nützliche, nicht-marketingbezogene Kontext rund um Plattform-Abwägungen, Personal, Wartungserwartungen bietet. Es lohnt sich, diese vor der Verpflichtung Ihres Überwachungs- und Release-Prozesses um eine gemeinsame Codebasis zu lesen.

Installieren Sie das SDK mit dem Assistenten aus dem Projektroot:

npx @sentry/wizard@latest -i reactNative

Der Assistent fragt einige Dinge, die Entwickler oft zu schnell durchklicken:

• Project selection. Wählen Sie das tatsächliche Sentry-Projekt, das Sie in der Produktion verwenden möchten, und nicht ein temporärer Sandbox, den Sie später vergessen werden.
• Native-Änderungen. Ja sagen. Eine JavaScript-basierte Fehlerfassung reicht für mobile Apps nicht aus.
• Zusätzliche Funktionen. Aktivieren Sie nur die Funktionen, die Sie wissen, dass Sie benötigen, aber nicht alles gleichzeitig aktivieren, wenn Ihr Team die resultierenden Daten nicht überprüfen wird.

Das Wizard ausführen und das Ergebnis überprüfen

Nachdem der Zauberer fertig ist, überprüfen Sie die Änderungen anstatt ihnen ohne Überprüfung zu vertrauen. Sie sollten ein Sentry-Paket sehen. package.jsonnative Änderungen unter ios und android, und einen Initialisierungsblock in Ihrem Anwendungs-Einstiegsskript.

Eine typische Initialisierung sieht so aus:

import * as Sentry from '@sentry/react-native';

Sentry.init({
  dsn: 'YOUR_DSN',
});

Die DSN zeigt dem SDK an, wohin Ereignisse gesendet werden sollen. Behandeln Sie es als Konfiguration und nicht als ein geheimes Verzeichnis, das niemals sichtbar sein darf. Es ist nicht dasselbe wie ein Authentifizierungstoken. Halten Sie Ihre Umgebungsvariablen jedoch sauber und konsistent, damit Ihre App auf die richtige Sentry-Projektumgebung in jeder Umgebung verweist.

Eine praktische Vorgehensweise besteht darin, die DSN aus umgebungsabhängiger Konfiguration zu laden und Sentry vor dem Rest Ihres App-Tree zu initialisieren. Wenn Sie auch durch die Politur der Startphase arbeiten, ist diese Anleitung zur React Native Splash Screen Konfiguration nützlich, da die Startphase des code oft mit der Platzierung der Sentry-Initialisierung durch Teams überschneidet.

Praktische Regel: Sentry so früh wie möglich in der App-Startphase initialisieren. Wenn Sie bis zum Nachladen wartet, Authentifizierung oder Remote-Konfiguration, werden Sie Startfehler verpassen.

Zu diesem Zeitpunkt sollten Sie sich nicht auf Perfektion konzentrieren. Das sofortige Ziel ist einfach: Die App starten, später in diesem Artikel einen JavaScript-Fehler auslösen und bestätigen, dass Ereignisse bei Sentry ankommen. Sobald das funktioniert, werden die native und release-Schichten viel einfacher zu verstehen.

Konfiguration von Native iOS- und Android-Projekten

Zu diesem Zeitpunkt bekommen viele React Native-Teams einen falschen Eindruck der Vollständigkeit. Die JavaScript-SDK ist installiert, Ereignisse erscheinen und alle denken, dass Crash-Reporting abgeschlossen ist. Es ist nicht der Fall. Wenn die native Integration ausgeschaltet ist, werden einige der Crashes, die Sie am meisten fürchten, nie bei Sentry in einer verwendbaren Form ankommen.

Welche Änderungen auf iOS

Öffnen Sie das iOS-Projekt und überprüfen Sie, was der Zauberer geändert hat. In einer leeren React Native-Anwendung bedeutet das normalerweise Updates in Bezug auf die Anwendungsstart- und Buildphasen. Sie suchen nach Sentry-Initialisierungshooks und Uploadschritten, die mit Ihrem Buildprozess verbunden sind.

In Xcode überprüfen Sie diese Orte:

• App-Delegate-Start code. Das App benötigt eine native Sentry-Initialisierung frühzeitig bei der Startphase.
• Build-Phasen. Suchen Sie nach einem Sentry-Upload-Script, das mit Debugsymbolen oder Sourcemap-Handling verbunden ist.
• Build-Einstellungen und Archivverhalten. Symboldateien müssen während der Archivbuilds generiert und verfügbar sein.

Wenn Ihr App AppDelegate.mmdie Initialisierung sitzt oft nahe bei der React Native-Bridge-Bootstrapping. Die genaue Dateiinhalt kann je nach React Native-Version, Template und ob Sie die neue Architektur verwenden, variieren, also kopieren Sie keine Snippets aus zufälligen Repositories, es sei denn, sie passen Ihrem Projektformat.

Wichtig ist die Absicht: iOS-native Crashs benötigen Symboldaten, und die App muss Sentry vor dem Crash zuverlässig beobachten können.

Wenn iOS-Crashs in Sentry mit nicht lesbaren native Frames erscheinen, ist das Problem normalerweise nicht "Sentry ist kaputt." Es ist die Symbol-Upload- oder Release-Matching-Problematik.

Was hat sich auf Android geändert

Android fügt normalerweise Änderungen in Gradle-Dateien und manchmal Konfigurationsebenen hinzu. Überprüfen Sie android/build.gradle, android/app/build.gradle, und jede SENTRY-bezogene Plugin- oder Aufgabenverkabelung.

Dinge zu überprüfen:

1. Die Sentry-Gradle-Plugin ist angewendet damit Release-Artikel während der Buildzeit verarbeitet werden können.
2. Die Variante-Verwaltung ist sinnvoll wenn Sie Produktflavors oder mehrere Buildtypen verwenden.
3. ProGuard- oder R8-Ausgaben werden berücksichtigt wenn Ihre Release-Builds schrumpfen oder verschleieren code.

Ein häufiger Fehler bei Android ist das Annehmen, dass ein erfolgreicher lokale Debug-Test beweist, dass die Release-Konfiguration korrekt ist. Es tut das nicht. Der Release-Weg ist anders, insbesondere wenn Minifizierung und CI-Signierung im Spiel sind. Wenn Ihr Team separate Debug-, Staging-, QA- und Store-Builds verwaltet, ist diese Auflistung der Mobilbauarten Eine nützliche Referenz für die Anpassung der Überwachungsverhalten an jede Build-Variante.

Native-Einstellungen, die später Zeit sparen.

Keine Sorge, wenn der Zauberer Dateien geändert hat. Überprüfe das Verhalten direkt.

Verwende diese Liste:

• Eine lokale iOS-Build-Archivierung erstellen und bestätige, dass die Veröffentlichung während der Symbolverarbeitung nicht fehlschlägt.
• Eine Release-Android-Build erstellen und die CI-Protokolle für Sentry-bezogene Aufgaben überprüfe.
• Überprüfe die Paketnamen- und Bundle-Identifier-Zuordnung in Sentry, wenn Sie mehrere Apps unter einer Organisation verwalten.
• Bekräftige die Versionsbezeichnungen jetzt, bevor die CI-Artikel unter inkonsistenten Namen hochlädt.

Das hier funktioniert normalerweise nicht gut:

Die beste Konfiguration ist langweilig. Die native Start-Hooks sind im Einsatz, die Build-Skripte laufen immer und die Release-Namen sind deterministisch über iOS, Android und JavaScript-Bundles.

Automatisierung von Releases und Source Maps

Wenn es ein Ort gibt, an dem die Sentry-React-Native-Konfigurationen auseinanderfallen, ist es hier. Teams installieren den SDK, sehen Ereignisse und verzögern die Automatisierung der Releases. Dann kommt das erste ernsthafte Produktionsproblem herein und die Stack-Spur ist minimiert, das Release fehlt oder die Upload-Datei für die Source Maps gehört zu einem anderen Bundle.

Händische Quellkartenuploads klingen akzeptabel, wenn Sie selten liefern. In der Praxis scheitern sie, weil Menschen bei wiederholter Release-Verwaltung schlecht sind.

Warum händische Uploads in der Praxis scheitern

Die Fehlerquellen sind vorhersehbar:

• Jemand vergisst, die Karten hochzuladen nach einem späten Nachmittags- Hotfix.
• Die hochgeladenen Dateien gehören zu einem anderen Commit als die Benutzer den binären oder OTA-Bundle ausführen.
• Der Release-Name ändert sich leicht zwischen iOS, Android und CI-Schritten.
• Ein Neubau erfolgt nach dem Upload der Karten und ungültigt, was Sentry abgleichen sollte.

Das ist der Grund, warum ich eine 'Die Schritte in Notion dokumentieren' -Methode nicht empfehle. Sie funktioniert, bis ein dringender Release unter Druck herausgeht.

Ein Release-Prozess, der tatsächlich funktioniert.

Ein zuverlässiger Setup hat einige Eigenschaften:

• Release-IDs werden einmal generiert und überall wiederverwendet. wieder verwendet.
• Sourcen werden von CI hochgeladen, nicht von einem Entwickler-Laptop..
• Quellabbildungen werden von CI hochgeladennicht von einem Entwickler-Notebook.
• Build, bundle, and upload steps happen in the same pipeline Source maps are uploaded from CI

Das letzte Punkt ist wichtiger als oft angenommen. Sie benötigen nicht nur Sourcemaps bei Sentry, Sie benötigen Die korrekten Sourcenabbilder, die der genauen Release-Identifikator entsprechen, der vom App-Programm bei der Ausführung emittiert wird..

Wenn Ihr Team bereits mobile Automatisierung standardisiert, folgen Sie diesem Leitfaden automatischer Build- und Release-Workflows mit GitHub Actions passt sich gut in das gleiche Betriebsmodell.

Ein praktisches CI-Skriptmuster

Verwenden Sie ein Skript wie dieses in CI und füllen Sie Werte aus Ihrem Pipeline-Umgebung ein:

#!/usr/bin/env bash
set -euo pipefail

export SENTRY_AUTH_TOKEN="$SENTRY_AUTH_TOKEN"
export SENTRY_ORG="your-org"
export SENTRY_PROJECT="your-project"

RELEASE_NAME="${APP_VERSION}+${GIT_SHA}"

npx sentry-cli releases new "$RELEASE_NAME"

npx react-native bundle \
  --platform ios \
  --dev false \
  --entry-file index.js \
  --bundle-output ./dist/main.jsbundle \
  --sourcemap-output ./dist/main.jsbundle.map

npx sentry-cli releases files "$RELEASE_NAME" upload-sourcemaps ./dist \
  --rewrite \
  --strip-prefix "$(pwd)"

npx sentry-cli releases finalize "$RELEASE_NAME"

Sie müssen die Befehlszeile für Android anpassen und viele Teams teilen Plattform-spezifische Aufgaben anstatt eine Skript zu zwingen, beide zu tun. Das ist in Ordnung. Was zählt ist Konsistenz.

Ein Release-Diskurs schlägt cleveres Scripting. Wählen Sie eine Namenskonvention, injizieren Sie sie in die App bei der Build-Zeit und lassen Sie es nie mit lokalen Ad-hoc-Uploads konkurrieren.

Für React Native bevorzuge ich die Speicherung der Release-Zeichenfolge in einer build-generierten Konfigurationslocation und die Lesung während Sentry.init():

Sentry.init({
  dsn: Config.SENTRY_DSN,
  release: Config.SENTRY_RELEASE,
  dist: Config.SENTRY_DIST,
});

Der Gewinn ist einfach. Wenn ein Ereignis eintritt, kann Sentry die minimierte Frame zurück auf den code mappen, den Sie verschickt haben, nicht auf den code den Sie glauben, dass Sie verschickt haben.

Leistungserfassung und benutzerdefinierte Ereignisse erfassen

Crashes sagen Ihnen, was gebrochen ist. Leistungstracing sagt Ihnen, was Benutzer vorher gefühlt haben, bevor sie aufgaben.

A häufige Meldung klingt wie folgt: „Das Dashboard ist langsam.“ Das reicht nicht aus, um zu debuggen. Langsam wo? Bei der Navigation? Während der Datenabfrage? Während der Renderung eines aufwendigen Charts? Sentry wird hier nützlich, wenn Sie aufhören, es wie einen Fehlerposteingang zu behandeln und stattdessen das Anwendungsverhalten instrumentieren.

Anstatt zu spekulieren, eine langsame Anzeige nachverfolgen

Beginnen Sie damit, Leistungstracing in Ihrer Initialisierung zu aktivieren. Die genaue Abtaststrategie hängt von Ihrer Umgebung und Ihrem Volumen-Toleranz ab, aber die Struktur sieht wie folgt aus:

Sentry.init({
  dsn: Config.SENTRY_DSN,
  tracesSampleRate: 1.0,
});

Wenn Sie React Navigation verwenden, integrieren Sie die Verbindung so, dass die Bildschirmübergänge Spuren erzeugen. Dann reproduzieren Sie den Vorwurf auf einem physischen Gerät, nicht nur auf einem Simulator. Simulatoren verbergen den Art der Schwäche, die Benutzer bemerken.

Ein praktisches Dashboard-Beispiel:

1. Ein Benutzer öffnet das Hauptdashboard nach dem Anmelden.
2. Die Navigation ist abgeschlossen, aber der Inhalt erscheint verspätet.
3. Die Spur zeigt, dass die Bildschirmanzeige lange dauert.
4. Kind-Spuren offenbaren einen API-Anfrage und einen teuren Render-Pfad.
5. Sie optimieren den Render-Pfad, schicken ihn wieder ab und vergleichen die neue Spurform.

Das ist besser als aus dem Bauch zu fühlen.

Für Teams, die breit über Webview- oder hybride App-Monitoringmuster nachdenken, ist dieser Artikel über Leistungsüberwachung in Capacitor-Projekten wirksam, da der operative Mindset ähnlich ist, obwohl die Stack unterschiedlich ist.

Die Hinzufügung nützlicher Kontextinformationen zu Fehlern

Leistungsdaten werden nützlicher, wenn Ereignisse Geschäfts-Kontext tragen. Nicht Selbstzweck-Metadaten. Nur genug, um zu beantworten, wer betroffen war, welche Seite sie gerade betrachteten und was vor dem Scheitern passierte.

Benutze diese Werkzeuge absichtlich:

• Benutzer-Kontext mit Sentry.setUser() damit der Support Berichte an einen betroffenen Account ohne Durchstöbern von Vermutungen korrelieren kann.
• Breadcrumbs für Aktionen wie das Absenden, das Öffnen eines Modals oder das Starten einer Synchronisierung.
• Custom tags für Dimensionen wie Plan-Typ, Status von Feature-Flags oder API Region.
• Fehlgeschlagene Ausnahmen mit zusätzlichen Kontext Wenn Sie Fehler fangen und wieder werfen oder beherrschte Fehler freilegen.

Beispiel:

Sentry.setUser({
  id: user.id,
  email: user.email,
});

Sentry.addBreadcrumb({
  category: 'navigation',
  message: 'Opened dashboard screen',
  level: 'info',
});

try {
  await loadDashboard();
} catch (error) {
  Sentry.captureException(error, {
    tags: { screen: 'dashboard' },
    extra: { widget: 'balance-summary' },
  });
}

A breadcrumb trail is often the difference between “user says the app froze” and “the app failed after opening dashboard, starting sync, and retrying a stale request.”

Wenn benutzerdefinierte Instrumentierung schief geht, geht es meistens schief, indem sie zu laut ist. Fassen Sie nicht jeden Tastenknopfdruck im App für immer ein. Fassen Sie Grenzen, Zustandsübergänge und wichtige Operationen ein, wenn Sie debuggen. Genug Kontext, um das Ereignis zu erklären. Nicht genug, um es zu ertränken.

Überprüfen und Fehlerbehebung Ihrer Integration

Sie sollten Sentry vor der Veröffentlichung, nach Änderungen im Build-Pipeline und nach SDK-Upgrades überprüfen. „Es funktionierte Monate her“ ist kein bedeutender Test.

Der sauberste Weg ist, kontrollierte Fehler für beide JavaScript- und native-Pfade auszulösen und dann zu überprüfen, wie sie in Sentry landen.

Sichere Auslösung von Testereignissen

Für einen JavaScript-Fehler fügen Sie einen temporären Button in einer nicht-produktiven Anzeige ein:

<Button
  title="Trigger JS Error"
  onPress={() => {
    throw new Error('Test JavaScript Sentry error');
  }}
/>

Für einen erfassten Fehler, der die App nicht abstürzen lässt:

<Button
  title="Capture Exception"
  onPress={() => {
    Sentry.captureException(new Error('Handled Sentry test error'));
  }}
/>

Native-Crash-Tests sollten sorgfältig und nur in der Entwicklung oder einem kontrollierten QA-Build durchgeführt werden. Die genauen Hilfsfunktionen, die zur Verfügung stehen, können je nach SDK-Version und Plattform-Verbindung variieren, daher bevorzuge ich die Verwendung der dokumentierten native Crash-Test-Utility von SDK anstelle der Erfindung eigener Crash-Pfade.

Was im Sentry-UI zu überprüfen ist

Wenn das Ereignis erscheint, überprüfe mehr als den Titel.

Überprüfe diese Felder:

• Plattform und Mechanismus . Dies hilft, JavaScript-Fehler von nativen Abstürzen zu unterscheiden.
• Release und dist . Wenn sie leer oder falsch sind, werden Source-Maps und Symbolisierung aus dem Gleichgewicht geraten.
• Stack-Frames . Lesbarer Quellort sollte für korrekt hochgeladene JavaScript-Maps erscheinen.
• Breadcrumbs und Tags. Confirm your custom context arrived.
• UmgebungStellen Sie sicher, dass sich Entwicklung und Produktionsereignisse nicht in einem Stream vermischen.

Wenn ein natives Ereignis eintrifft, aber schlechte Symbolisierung hat, ändern Sie nicht weiter das code. Das ist meist ein Problem mit dem Build-Artifact.

Häufige Probleme bei Sentry React Native

Ein letzter Gewohnheit, der sich auszahlt, ist das Halten eines kleinen „Überwachungs-Smoke-Test“-Checklisten im Release-Prozess. Auslösen Sie einen JS-Ereignis in der Staging-Umgebung, bestätigen Sie die Release-Werte und überprüfen Sie die Quellorte, bevor Sie ein Build vorantreiben.

Integrieren Sie mit Live Update Workflows wie Capgo

Live-Updates ändern das Release-Modell. Das Binärdatei im Store bleibt gleich, während die JavaScript-Bundle unterhalb davon sich ändern. Wenn Sentry immer noch nur an die ursprüngliche App-Version denkt, werden die Stapelspuren schnell irreführend.

Die Lösung besteht darin, Die Sentry-Release-Identität folgt dem lebenden Bundleund nicht nur dem nativen Binärdatei.

Übereinstimmende Release-Identifikatoren mit lebenden Bundles

Für live update Workflows behandeln Sie release und dist als Laufzeitidentifikatoren, die mit dem gelieferten JavaScript-Paket verbunden sind. Die native App-Version ist immer noch wichtig, aber sie reicht nicht aus, sobald sich die Bundles unabhängig voneinander ändern können.

Eine praktische Muster sieht so aus:

• Verwenden Sie die native App-Version als Teil des Basis-Release-Namens.
• Fügen Sie die live update-Version oder -Paket-Identifikator hinzu.
• Verwenden dist sie für kanal- oder build-spezifische Differenzierung, wenn das zu Ihrem Modell passt.
• Hochladen Sie Quellkarten für jeden Live-Bundle unter genau diesem Release-Identifikator.

Beispiel: Wenn Ihre App bei dem Start die Update-Metadaten lädt, initialisieren Sie Sentry mit Werten, die aus dem derzeit aktiven Bundle abgeleitet werden und nicht nur aus der statischen Build-Konfiguration.

Sentry.init({
  dsn: Config.SENTRY_DSN,
  release: activeBundle.releaseName,
  dist: activeBundle.channel,
});

Damit, wenn ein Benutzer bei einem hotfixierten Bundle einen Fehler trifft, löst Sentry die Frames gegen die Quellkarte für diesen Hotfix auf und nicht gegen die ältere Store-Bundle.

Dies ist wichtig bei jedem OTA-Workflow. Wenn Sie eine gute Einführung in die beweglichen Teile hinter diesem Liefermodell wünschen, finden Sie eine Erklärung hier. Wie Live-Updates in Capacitor-Apps funktionieren ist eine solide Referenz.

Hier ist der Art von Betriebsbild, das Teams anstreben, wenn sie Update-Metadaten mit der Veröffentlichungsverfolgung kombinieren:

Der Hauptfehler, den man vermeiden sollte, ist die Wiederholung einer statischen Veröffentlichungszeichenfolge für jede post-Store-Update. Wenn mehrere Pakete dieselbe Sentry-Veröffentlichung teilen, wird das Debuggen wieder zu einem Rätselraten.

Wenn Ihr Team Reparaturen außerhalb der App-Store-Bewertungszyklen verschickt Capgo ist wertvoll. Es gibt Capacitor-Teams eine strukturierte Möglichkeit, Live-Updates bereitzustellen, Kanäle anzusprechen, Rollouts zu steuern und sich schnell von schlechten Veröffentlichungen zu erholen. Paaren Sie das mit einer disziplinierten Sentry-Veröffentlichungsbezeichnung und Uploads von Quellkarten, und Sie erhalten einen Workflow, bei dem Fehler immer noch auf die genauen code-Benutzer hinweisen, die code laufen.