06. Juli 2026

Sentry React Native: Leitfaden für die Integration 2026

Sie haben eine React Native-Anwendung lokal laufen, die QA hat zugestimmt und die Produktion ist nah. Dann landet die offensichtliche Frage: Was passiert, wenn sie auf einem Gerät des Benutzers kaputt geht? Die grundlegende Installation ist das Einfache Teil.. Die schmerzhaften Teile kommen später: native Integration, Symbolisierung, Quellkarten, Release-Naming und das Festhalten an allem, wenn Ihr Liefermodell Live-Updates beinhaltet.

Die meisten Anleitungen enden zu früh. Eine echte Konfiguration muss CI, App Store Builds, Android-Veröffentlichungen und JavaScript-Bundles überstehen, die nicht immer aus dem Original-Code stammen.

Inhaltsverzeichnis

• Kurzanleitung für die Einrichtung von Sentry SDK
  • Was Sie vor der Installation benötigen
  • Der Assistent ausführen und das Ergebnis überprüfen
• Konfigurieren Sie Native iOS- und Android-Projekte
  • Was ändert sich auf iOS
  • Was ändert sich auf Android
  • Native Setup-Überprüfungen, die Ihnen später Zeit sparen
• Automatisierung von Releases und Quellkarten
  • Warum manuelle Uploads in der Praxis scheitern
  • Ein Release-Prozess, der tatsächlich funktioniert
  • Ein praktisches CI-Skriptmuster
• Leistungsmessdaten und benutzerdefinierte Ereignisse erfassen
  • Stattdessen eine langsame Anzeige nachverfolgen
  • Nützliche Kontextinformationen zu Fehlern hinzufügen
• Ihre Integration überprüfen und Fehler beheben
  • Sicherheitstests auslösen
  • Was Sie im Sentry-UI überprüfen sollten
  • Häufige Probleme bei der Integration von Sentry React Native
• Integration mit Live-Update-Workflows wie Capgo
  • Release-Identifikatoren mit Live-Bundles abgleichen

Mit Sentry SDK beginnen

Die schnellste Möglichkeit, Sentry React Native in eine neue App zu integrieren, ist immer noch der Installations-Assistent. Er übernimmt den größten Teil der wiederholten Einstellungen und bringt Sie schnell zu einem funktionierenden Grundlevel. Das ist wichtig, weil die Handarbeit bei der ersten Installation normalerweise zu kleinen Abweichungen führt, die Sie erst bei der ersten Produktionspanne bemerken.

Was Sie vor der Installation benötigen

Zunächst benötigen Sie ein normales React Native-Entwicklungsumfeld. Node, ein Paketmanager, Plattform-Tools für iOS und Android und 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 evaluiere, ob React Native die richtige Betriebswahl für Ihr Team ist, gibt es eine React Native-Richtlinie für Unternehmen die nützliche, nicht-marketingbezogene Kontextinformationen über Plattform-Abwägungen, Personal und Wartungserwartungen bietet. Es lohnt sich, diese vor der Verpflichtung Ihres Überwachungs- und Release-Prozesses um eine gemeinsame Codebasis zu lesen.

Installieren Sie die SDK mit dem Assistenten vom Projekt-Root:

npx @sentry/wizard@latest -i reactNative

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

• Projektwahl. 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.
• Nativänderungen. Sag ja. Eine JavaScript-basierte Fehlerfassung reicht für mobile Apps nicht aus.
• Optionale Funktionen. Aktivieren Sie nur die Funktionen, die Sie wissen, dass Sie benötigen, aber nicht alles gleichzeitig auf einmal, wenn Ihr Team die Ergebnisse nicht überprüfen kann.

Das Ausführen des Wizards und die Überprüfung der Ergebnisse

Nachdem der Wizard abgeschlossen ist, überprüfen Sie die Änderungen anstatt ihnen ohne Überprüfung zu vertrauen. Sie sollten ein Sentry-Paket in package.jsonnative Änderungen unter ios und androidund eine Initialisierungseinheit in Ihrem Anwendungsstartdatei finden.

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 die Ereignisse gesendet werden sollen. Behandeln Sie es als Konfiguration, nicht als ein Geheimnis, das niemals sichtbar sein darf. Es ist nicht dasselbe wie ein Authentifizierungstoken. Halten Sie jedoch Ihre Umgebungsinstellungen sauber und konsistent, damit Ihre App auf die richtige Sentry-Projekt in jeder Umgebung zeigt.

A praktische Muster ist, die DSN aus der Umgebungs- spezifischen Konfiguration zu laden und Sentry vor dem Rest deiner App-Tree zu initialisieren. Wenn du auch durch die Polishing von Startups arbeitest, ist diese Anleitung zu den React Native Splash Screen Einstellungen nützlich, weil die Start- code -Reihenfolge oft mit dem Ort überschneidet, an dem Teams Sentry initialisieren.

Praktische Regel: Sentry so früh wie möglich in der App-Start-Phase initialisieren. Wenn du wartest, bis nach der Navigation, Auth-Hydratation oder Remote-Konfiguration, wirst du Startfehler verpassen.

Zu diesem Zeitpunkt solltest du nicht nach Perfektion streben. Das sofortige Ziel ist einfach: Das App-Programm starten, später einen JavaScript-Fehler auslösen und bestätigen, dass Ereignisse bei Sentry ankommen. Sobald das funktioniert, werden die native und die 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. Das JavaScript- SDK ist installiert, Ereignisse erscheinen und jeder denkt, dass Crash-Reporting abgeschlossen ist. Es ist nicht.

Was hat sich auf iOS geändert

Öffne das iOS-Projekt und überprüfe, was der Zauberer geändert hat. In einer leeren React Native-App bedeutet das meist Updates um die App-Start- und Build-Phasen. Du suchst nach Sentry-Initialisierungshooks und Upload-Schritten, die mit deinem Build-Prozess verbunden sind.

In Xcode überprüfe diese Orte:

• App Delegate Start- codeDie App benötigt eine native Sentry-Initialisierung frühzeitig bei der Startphase.
• Build PhasenSuchen Sie nach jeder Sentry-Upload-Script-Beziehung zu Debugsymbolen oder Sourcemap-Verwaltung.
• Einstellungen für die Build- und ArchivverhaltenDie Symboldateien müssen generiert und während der Archivbuilds verfügbar sein.

Wenn Ihre App AppDelegate.mmDie Initialisierung von Sentry sitzt oft in der Nähe der Bootstrapping des React Native-Bridges. Die genauen Dateien können je nach React Native-Version, Vorlage und Verwendung der neuen Architektur variieren, daher sollten Sie keine Snippets aus zufälligen Repositories kopieren, es sei denn, sie passen zu Ihrem Projektformat.

Was zählt 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 meist 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 den Gradle-Dateien und manchmal auch Manifest-Ebene-Konfiguration hinzu. Überprüfen Sie android/build.gradle, android/app/build.gradleund jede Sentry-zugehörige Plugin- oder Task-Verkabelung.

Dinge zu überprüfen:

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

Ein häufiger Fehler bei Android ist die Annahme, dass ein erfolgreicher lokaler Debug-Run beweist, dass die Release-Konfiguration korrekt ist. Das tut sie 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 dieser Abbruch der Mobile-Buildtypen eine nützliche Referenz für die Einhaltung der Überwachungsverhalten bei jedem Build-Varianten.

Native-Einstellungen, die Zeit sparen

Kommen Sie nicht bei 'Der Zauberer hat Dateien geändert.' an. Überprüfen Sie das Verhalten direkt.

Verwenden Sie diese Liste der Kontrollpunkte:

• Archivieren Sie eine lokale iOS-Build-Version und bestätigen Sie, dass die Verarbeitung von Symbolen während der Erstellung nicht fehlschlägt.
• Erstellen Sie eine Release-Android-Build-Version und überprüfen Sie die CI-Protokolle für Sentry-bezogene Aufgaben.
• Überprüfen Sie die Paketnamen- und Bundle-Identifier-Kartierung in Sentry, wenn Sie mehrere Apps unter einer Organisation verwalten.
• Bestätigen Sie die Konventionen für die Versionsnamen, bevor CI unter inkonsistenten Namen Artefakte hochlädt.

Hier sind die Dinge, die normalerweise nicht gut funktionieren:

Die beste Konfiguration ist langweilig. Die native Startup-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 auseinanderbrechen, ist es hier. Teams installieren den SDK, sehen Ereignisse und verschieben die Automatisierung der Releases. Dann kommt das erste ernsthafte Produktionsproblem und der Stacktrace ist minimiert, der Release fehlt oder die Upload-Datei für die Source Maps gehört zu einem anderen Bundle.

Manuelle Source-Map-Uploads klingen akzeptabel, wenn Sie selten liefern. In der Praxis scheitern sie, weil Menschen schlecht bei wiederholten Release-Verwaltungsaufgaben sind.

Warum manuelle Uploads in der Praxis scheitern

Die Fehlerarten sind vorhersehbar:

• Jemand vergisst, die Karten hochzuladen nach einer spätnächtlichen Hotfix.
• Die hochgeladenen Dateien gehören zu einem anderen Commit als dem, der die binäre oder OTA-Paket-User ausführen.
• Der Release-Name ändert sich leicht zwischen iOS, Android und CI-Schritten.
• Ein Neubau erfolgt nach der Karten-Hochladung und ungültigt, was Sentry gegenüber abgleichen sollte.

Deshalb empfehle ich nicht eine "die Schritte in Notion dokumentieren"-Methode. Sie funktioniert, bis ein dringender Release unter Druck herausgeht.

Ein Release-Prozess, der wirklich hält

Ein zuverlässiger Setup hat einige Eigenschaften:

• Release-IDs werden einmal generiert und überall wiederverwendet.
• Die Build-, Bundle- und Upload-Schritte finden in derselben Pipeline statt.
• Quellkarten werden von CI hochgeladennicht von einem Entwickler-Notebook.
• Die App initialisiert Sentry mit dem gleichen Release-String der CI während des Uploads verwendet hat.

Dieser letzte Punkt ist wichtiger als oft angenommen. Sie benötigen nicht nur Quellkarten in Sentry. Sie benötigen die richtigen Quellkarten, die an dem genauen Release-Identifier angehängt sind, der vom App am Laufzeitpunkt ausgegeben wird.

Wenn Ihr Team bereits mobile Automatisierung standardisiert hat, passt sich diese Anleitung zu automatischen Build- und Release-Workflows mit __CAPGO_KEEP_0__ Actions gut in das gleiche Betriebsmodell. automatic build and release workflows with GitHub Actions Die App initialisiert Sentry mit dem gleichen Release-String, der CI verwendet hat.

A praktische 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 Sie Plattform-spezifische Aufgaben anstatt eine Skript zu zwingen, beide zu tun. Das ist in Ordnung. Was zählt ist Konsistenz.

Die Disziplin der Veröffentlichung besiegt cleveres Scripting. Wählen Sie eine Namenskonvention, injizieren Sie sie in die App bei der Buildzeit und lassen Sie keine lokalen Ad-hoc-Uploads mit CI konkurrieren.

Für React Native bevorzuge ich die Speicherung der Release-String 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, und nicht auf den code , den Sie glauben, verschickt zu haben.

Leistungsmessung und benutzerdefinierte Ereignisse erfassen

Crashes erzählen Ihnen, was gebrochen ist. Leistungstracing erzählt Ihnen, was die Benutzer vorher gefühlt haben, bevor sie aufgaben.

Ein gemeinsamer Bericht klingt wie folgt: „Die Dashboard ist langsam.“ Das ist nicht genug, um zu debuggen. Langsam wo? Bei der Navigation? Während der Datenabfrage? Während der Renderung eines schweren Charts? Sentry wird hier nützlich, wenn Sie aufhören, es wie einen Fehlerposteingang zu behandeln und anstatt dessen das App-Verhalten instrumentieren.

Ein Bild von einem Softwareentwickler, der auf einem Laptop codet, mit Datenvisualisierungsdarstellungen auf einem Hintergrundmonitor.

Beginnen Sie mit der Aktivierung der Leistungstracing in Ihrer Initialisierung. Die genaue Abtaststrategie hängt von Ihrer Umgebung und Ihrer Volumen-Toleranz ab, aber die Struktur sieht so aus:

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

Wenn Sie React Navigation verwenden, verbinden Sie die Integration so, dass die Übergänge zwischen den Bildschirmen Daten für die Spuren produzieren. Dann reproduzieren Sie den Vorwurf auf einem physischen Gerät und nicht nur auf einem Simulator. Simulatoren verbergen den Arten von Schwere, 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 Bildschirmtransaktion lang ist.
4. Die Kinderspuren offenbaren einen API-Anforderung und einen teuren Render-Pfad.
5. Sie optimieren den Render-Pfad, schicken ihn erneut und vergleichen die neue Spurform.

Das ist besser als aus dem Bauchgefühl zu argumentieren.

Für Teams, die breit über die Überwachung von Webview- oder Hybrid-App-Muster denken, ist diese Schriftstück über die Leistungsoberwachung in Capacitor-Projekten würdig, weil der operative Denkansatz ähnlich ist, auch wenn die Stacks sich unterscheiden.

Erkennung nützlicher Kontextinformationen zu Fehlern

Leistungsdaten werden nützlicher, wenn Ereignisse Geschäfts-Kontextinformationen enthalten. Nicht Selbstzweck-Metadaten. Nur genug, um zu beantworten, wer betroffen war, auf welcher Seite sie waren und was vor dem Fehler passierte.

Benutze diese Werkzeuge absichtlich:

• Benutzer-Kontext mit Sentry.setUser() damit der Support Berichte an einen betroffenen Account ohne Durchsuchen von Vermutungen korrelieren kann.
• Breadcrumbs zurückzuliefern von Aktionen wie das Anklicken von 'Absenden', das Öffnen eines Modals oder das Starten eines Synchronisierungsprozesses.
• Benutzerdefinierte Tags zurückzuliefern von Dimensionen wie Abonnementstyp, Status von Feature-Flags oder API Region.
• Fehlertypen mit zusätzlichen Kontextinformationen bei der Wiederholung oder Oberflächensurfacing von kontrollierten Fehlern.

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' },
  });
}

Eine Brotkrumen-Spur kann oft der Unterschied zwischen „Der Benutzer sagt, dass das App gefroren ist“ und „Die App ist nach dem Öffnen des Dashboard, dem Starten der Synchronisierung und dem Wiederholen eines veralteten Anforderung fehlgeschlagen“ sein.

Wenn die benutzerdefinierte Instrumentierung schief geht, geht sie meistens schief, indem sie zu laut ist. Fassen Sie nicht jeden Tastendruck in der App für immer ein. Fassen Sie die Grenzen, die Zustandsübergänge und die Operationen ein, die beim Debugging relevant sind. Genug Kontext, um das Ereignis zu erklären. Nicht genug, um es zu ersticken.

Überprüfen und Fehlerbeheben 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.

Die sauberste Methode ist es, 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 Ausnahmefall, der das App nicht abstürzen lässt:

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

Native-Crash-Testen sollten sorgfältig und nur in der Entwicklung oder in kontrollierten QA-Builds durchgeführt werden. Die genauen Hilfsmethoden, die verfügbar sind, können je nach SDK-Version und Plattform-Verkabelung variieren, daher bevorzuge ich die Verwendung der SDK-dokumentierten native-Crash-Test-Utility, wenn sie vorhanden ist, anstatt eigene Crash-Pfade zu erfinden.

Was Sie im Sentry-UI überprüfen sollten

Wenn das Ereignis erscheint, untersuchen Sie mehr als nur den Titel.

Überprüfen Sie diese Felder:

• Plattform und MechanismusDies hilft, JS-Ausnahmen von nativen Crashs zu unterscheiden.
• Veröffentlichung und distWenn sie leer oder falsch sind, werden Source Maps und Symbolikation aus dem Gleichgewicht geraten.
• StackrahmenLesbarer Quellort sollte für korrekt hochgeladene JavaScript-Karten erscheinen.
• Brotkrumen und TagsBestätigen Sie, dass Ihr benutzerdefinierter Kontext eingetroffen ist.
• UmgebungStellen Sie sicher, dass sich Entwicklung und Produktionsereignisse nicht in einem Stream vermischen.

Wenn ein natives Ereignis eintritt, aber eine schlechte Symbolisierung hat, ändern Sie nicht weiter Ihr code. Das ist meist ein Problem mit dem Build-Artikel.

Häufige Probleme bei Sentry React Native

Eine letzte Gewohnheit, die sich auszahlt, ist das Halten eines kleinen "Überwachungsrauchtest"-Checklisten in Ihrem Release-Prozess. Triggeren Sie einen JS-Ereignis in der Staging-Umgebung, bestätigen Sie die Release-Werte und überprüfen Sie die Quellorte, bevor Sie ein Build voranbringen.

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 unter ihr sich ändern. Wenn Sentry immer noch nur an den ursprünglichen App-Version denkt, werden die Stapelspuren schnell irreführend.

Die Lösung ist, dass Sentry-Release-Identität dem Live-Bundle folgt, nicht nur dem nativen Binärdatei.

Übereinstimmende Release-Identifikatoren mit Live-Bundles

Für Live-Update-Workflows behandeln Sie release und dist context

als Laufzeit-Identifikatoren, die an das gelieferte JavaScript-Paket gebunden sind. Die native App-Version ist immer noch wichtig, aber sie ist nicht ausreichend, sobald sich die Bundles unabhängig voneinander ändern können.

• Verwenden Sie die native App-Version als Teil des Basis-Release-Namens.
• Hängen Sie die lebendige Update-Version oder den Paket-Identifikator an.
• Verwenden Sie dist für die Kanal- oder Build-spezifische Differenzierung, wenn das zu Ihrem Modell passt.
• Hängen Sie Quellkarten für jeden lebendigen Bundle unter genau diesem Release-Identifikator hoch.

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, nicht nur aus der statischen Build-Konfiguration.

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

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

Dies ist bei jedem OTA-Workflow wichtig. Wenn Sie eine gute Einführung in die beweglichen Teile hinter diesem Liefermodell wünschen, ist diese Erklärung von wie live Updates in Capacitor-Apps eine solide Referenz.

Hier ist der Art von Betriebsansicht, die Teams anstreben, wenn sie Update-Metadaten mit Release-Tracking kombinieren:

Hauptfehler zu vermeiden ist die Wiederholung einer statischen Release-String für jede Post-Store-Update. Wenn mehrere Pakete denselben Sentry-Release teilen, wird das Debuggen wieder zu einem Raten.

Wenn Ihr Team außerhalb der App-Store-Bewertungszyklen Fixes bereitstellt, Capgo ist es wert, zu bewerten. Es gibt Capacitor Teams eine strukturierte Möglichkeit, live Updates bereitzustellen, Zielkanäle anzusteuern, Rollouts zu kontrollieren und sich schnell von schlechten Releases erholen. Paaren Sie das mit einer disziplinierten Namensgebung für Sentry-Releases und Uploads von Sourcen, und Sie erhalten einen Workflow, bei dem Fehler immer noch auf die genauen code-Benutzer hinweisen, die sie ausführen.