25. August 2026

Sentry React Native: Leitfaden zur 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 zusammenbricht? Die grundlegende Installation ist das Einfache.. Die schmerzhaften Teile kommen später: native Integration, Symbolisierung, Quellkarten, Release-Namen 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-Releases und JavaScript-Bundles überleben, die nicht immer aus dem Original-Code stammen.

Inhaltsverzeichnis

• Kapitel 1: Einführung in Sentry SDK
  • Was Sie vor der Installation benötigen
  • Das Wizard 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
  • Eine Veröffentlichungsprozess, der tatsächlich funktioniert
  • Eine praktische CI-Skriptmuster
• Leistungsmessdaten und benutzerdefinierte Ereignisse erfassen
  • Stattdessen eine langsame Bildschirmablaufspur nachverfolgen
  • Fehler mit nützlichen Kontexten hinzufügen
• Überprüfen und Ihre Integration beheben
  • Sicherheitstests auslösen
  • Was Sie im Sentry-UI überprüfen sollten
  • Gemeinsame Sentry-React-Native-Fehlerbehebungen
• Integrieren mit Live-Update-Workflows wie Capgo
  • Live-Bundles mit Release-Identifikatoren 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 Grundlayout. Das ist wichtig, weil die Handarbeit beim ersten Installieren normalerweise zu kleinen Ungleichheiten führt, die Sie erst bei der ersten Produktionspanne 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 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 Diese React Native-Richtlinie für Unternehmen nützliche, nicht-marketingbezogene Kontextinformationen zu Plattform-Entscheidungen, Personal, Wartungserwartungen. Es lohnt sich, diese zu lesen, bevor Sie Ihr Monitoring- und Release-Prozess um eine gemeinsame Codebasis herum festlegen.

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

npx @sentry/wizard@latest -i reactNative

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

• ProjektwahlWä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. JavaScript-basierte Fehlerfänge sind für mobile Apps nicht ausreichend.
• Optionale Funktionen. Aktivieren Sie nur die Funktionen, die Sie wissen, dass Sie benötigen, aber nicht alles gleichzeitig aktivieren, wenn Ihr Team die Ergebnisse nicht überprüfen kann.

Das Laufen 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 eine Sentry-Paket in package.jsonnative Änderungen unter ios und androidund eine Initialisierungsoberfläche in Ihrem Anwendungsstartdatei sehen.

Eine typische Initialisierung sieht wie folgt 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 Umgebungsvariablen sauber und konsistent, damit Ihre App auf die richtige Sentry-Projekt in jeder Umgebung zeigt.

A praktische Muster ist es, die DSN aus der Umgebungsabhängigen Konfiguration zu laden und Sentry vor dem Rest Ihres App-Tree zu initialisieren. Wenn Sie auch durch die Polishing von Startups arbeiten, ist diese Anleitung zu den __CAPGO_KEEP_0__ ist nützlich, weil die Start-__CAPGO_KEEP_0__-Reihenfolge oft mit dem Ort überschneidet, an dem Teams Sentry-Initialisierung platzieren. is useful because startup code order often intersects with where teams place Sentry initialization.

Sentry so früh wie möglich im App-Startup zu initialisieren. Wenn Sie bis zum Navigieren, Authentifizierung, oder Remote-Konfiguration warten, werden Sie Startfehler verpassen. Zu diesem Zeitpunkt sollten Sie sich nicht auf Perfektion konzentrieren. Das sofortige Ziel ist einfach: Das App starten, einen JavaScript-Fehler später in diesem Artikel 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-__CAPGO_KEEP_0__ ist installiert, Ereignisse erscheinen und jeder denkt, dass Crash-Reporting abgeschlossen ist. Es ist nicht.

At this stage, many React Native teams get a false sense of completion. The JavaScript SDK is installed, events show up, and everyone assumes crash reporting is done. It isn’t. If native integration is off, some of the crashes you care about most will never reach Sentry in a usable form.

Öffnen Sie das iOS-Projekt und überprüfen Sie, was der Zauberer geändert hat. In einem barem React-Native-App bedeutet das, dass Updates um App-Startup und Build-Phasen vorgenommen wurden. Sie suchen nach Sentry-Initialisierungs-Hooks und Upload-Schritten, die mit Ihrem Build-Prozess verbunden sind.

In Xcode überprüfen Sie diese Orte:

App-Delegate-Startup-__CAPGO_KEEP_0__

• App delegate startup code. Die App benötigt eine native Sentry-Initialisierung frühzeitig bei der Startphase.
• Build Phasen. Suche nach jeder Sentry-Upload-Script-Beziehung zu Debugsymbolen oder Sourcemap-Verwaltung.
• Build-Einstellungen und Archivverhalten. Symboldateien müssen generiert und während Archivbuilds verfügbar sein.

Wenn Ihre App AppDelegate.mm, sitzt die Initialisierung oft in der Nähe der React Native-Bridge-Bootstrapping.

Was zählt ist die Absicht: iOS-native Crashs benötigen Symbol-Daten, und die App muss Sentry vor dem Crash zuverlässig beobachten.

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

Was hat sich auf Android geändert

Android fügt normalerweise Änderungen in Gradle-Dateien und manchmal Manifest-Ebene-Konfiguration hinzu. Überprüfe android/build.gradle, android/app/build.gradle, und jede Sentry-zugehörige Plugin- oder Task-Verkabelung.

Dinge zu überprüfen:

1. Die Sentry-Gradle-Plugin wird angewendet damit Release-Artikel während der Buildzeit verarbeitet werden können.
2. Die Variante-Verwaltung ist korrekt wenn Sie Produktflavours 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 lokaler Debug-Test 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 Abgleich der mobileren Buildtypen eine nützliche Referenz für die Abstimmung der Überwachungsverhalten mit jedem Build-Varianten.

Native-Einstellungen, die Zeit sparen

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

Verwenden Sie diese Liste der Kontrollpunkte:

• Archivieren Sie eine lokale iOS-Build-Ausgabe und bestätigen Sie, dass die Ausführung während der Symbolverarbeitung nicht fehlschlägt.
• Erstellen Sie eine Android-Build-Ausgabe und überprüfen Sie die CI-Protokolle für Aufgaben, die mit Sentry zusammenhängen.
• Ü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 Artefakte unter inkonsistenten Namen hochlädt.

Hier sind die Dinge, die normalerweise nicht gut funktionieren:

Die beste Einrichtung ist langweilig. Die native Start-Hooks sind im Einsatz, die Build-Skripte laufen jedenfalls 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-Einrichtungen 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, der Release fehlt oder die Upload-Datei für die Source Maps gehörte 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-Bundle-Benutzer 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, die Schritte in Notion zu dokumentieren. Es 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.
• Build-, Bundle- und Upload-Schritte finden in derselben Pipeline statt.
• Quellkarten werden von CI hochgeladen, nicht 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 Laufzeitzeitpunkt ausgegeben wird.

Wenn Ihr Team bereits mobile Automatisierung standardisiert, passt sich diese Anleitung zu automatischen Build- und Release-Workflows mit GitHub Actions zu dem gleichen Betriebsmodell.

A praktische CI-Skriptmuster

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

#!/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 Bündelkommando 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 Veröffentlichungsdisziplin 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 Veröffentlichungszeichenfolge 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ückmappen auf die code Sie verschifft haben, nicht die code Sie glauben, verschifft zu haben.

Leistungsmessung und benutzerdefinierte Ereignisse erfassen

Crashes sagen Ihnen, was gebrochen ist. Leistungstracing sagt 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 die App-Verhaltensinstrumentierung beginnen.

Stattdessen die Leistung eines langsamen Bildschirms nachverfolgen, anstatt zu raten

Beginnen Sie mit der Aktivierung der Leistungstracing in Ihrer Initialisierung. Die genaue Abtaststrategie hängt von Ihrer Umgebung und Ihrem 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 Bildschirmübergänge Spuren-Daten erzeugen. Dann reproduzieren Sie den Beschwerde auf einem physischen Gerät, nicht nur auf einem Simulator. Simulatoren verbergen die Art der Schwäche, die Benutzer bemerken.

Ein praktisches Dashboard-Beispiel:

1. Ein Benutzer öffnet das Hauptdashboard nach dem Anmelden.
2. Navigation ist abgeschlossen, aber Inhalte erscheinen verspätet.
3. Die Spur zeigt, dass die Bildschirmtransaktion lang ist.
4. Kinder-Spuren offenbaren einen API-Anforderung und einen teuren Render-Path.
5. Sie optimieren den Render-Path, schicken ihn wieder und vergleichen die neue Spur-Form.

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

Für Teams, die breit über Webview- oder Hybrid-App-Monitoring-Muster nachdenken, ist diese Schriftstück über Leistungsmessung in Capacitor-Projekten würdig, weil der operative Denkansatz ähnlich ist, obwohl die Stacks sich unterscheiden.

Erweiterung von nützlichen Kontexten für Fehler

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

Verwenden Sie diese Werkzeuge absichtlich:

• Benutzer-Kontext mit Sentry.setUser() damit der Support Berichte an einen betroffenen Account ohne Durchsuchen von Vermutungen korrelieren kann.
• Breadcrumbs für Aktionen wie das Anklicken von
• Einblenden eines Modals oder Starten eines Synchronisierungsprozesses. for dimensions like plan type, feature flag state, or API region.
• für Dimensionen wie Tarifart, Flag-Status für Features oder __CAPGO_KEEP_0__ Region. Fehlertypen mit zusätzlichem Kontext

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

Ein Brotkrumenpfad ist oft der Unterschied zwischen „Benutzer sagt, dass das App gefroren ist“ und „Die App ist nach dem Öffnen des Dashboards, dem Starten der Synchronisation und dem erneuten Versuch einer veralteten Anfrage gescheitert.“

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, Zustandsübergänge und Operationen ein, die beim Debuggen 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.

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

Sichere Testereignisse auslösen

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-Testing sollte sorgfältig und nur in der Entwicklung oder in kontrollierten QA-Builds erfolgen. 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.
• Release und distWenn sie leer oder falsch sind, werden Source Maps und Symbolikation auseinanderdriften.
• StackrahmenLesbare Quellortung sollte für korrekt hochgeladene JavaScript-Maps 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-Artifact.

Häufige Probleme bei Sentry React Native

Eine letzte Gewohnheit, die sich auszahlt, ist das Halten eines kleinen "Überwachungs-Smoke-Test"-Checklisten in Ihrem 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 darunter sich ändert. Wenn Sentry immer noch nur an die ursprüngliche App-Version denkt, werden die Stapelabwurfs schnell irreführend.

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

Übereinstimmende Release-Identifikatoren mit lebenden Bundeln

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

Page/area: Capgo Marketing Website. Role: Kurze UI-Bezeichnung oder Navigationselement. Ansehen in: Seite trust.astro. Nachrichtsschlüssel `und` (Und).

• 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 dist für die Kanal- oder Build-spezifische Differenzierung, wenn das zu Ihrem Modell passt.
• Hängen Sie Quellkarten hoch, die für jeden lebendigen Bundle unter genau diesem Release-Identifikator liegen.

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

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 __CAPGO_KEEP_0__ Apps eine solide Referenz. how live updates work in Capacitor apps Bildquelle: https://__CAPGO_KEEP_0__.app

Bildquelle: https://__CAPGO_KEEP_0__.app

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 zu erholen. Paaren Sie das mit disziplinierten Sentry-Release-Namen und Quellkarten-Uploads und Sie erhalten einen Workflow, bei dem Fehler immer noch auf die genauen code-Benutzer hinweisen, die sie ausführen.