Sentry React Native: Guida all'integrazione 2026

Hai un'app React Native che funziona localmente, QA ha dato il via libera e la produzione è vicina. Poi arriva la domanda ovvia: cosa succede quando si rompe su un dispositivo dell'utente?

Senza Sentry, la risposta è spesso cattiva. Ricevi un ticket di supporto, uno screenshot vago, forse un console log da un build di sviluppo che non corrisponde alla produzione. Con Sentry React Native configurato correttamente, ricevi l'errore, lo stack, la release che l'ha spedito e abbastanza contesto per risolverlo senza indovinare. Il catch è che Installazione base è la parte facile. Le parti dolorose arrivano più tardi: integrazione nativa, simbolizzazione, mappe di origine, denominazione delle versioni di rilascio, e mantenere tutto allineato quando il modello di consegna include aggiornamenti in tempo reale.

La maggior parte delle guide si ferma troppo presto. Una configurazione reale deve sopravvivere a CI, costruzioni dell'App Store, rilasci Android e pacchetti JavaScript che non sempre provengono dal binario originale.

Indice dei contenuti

• Avvio con Sentry SDK
  • Cosa serve prima dell'installazione
  • Eseguire il wizard e revisionare il risultato
• Configurazione dei progetti nativi iOS e Android
  • Cosa è cambiato su iOS
  • Cosa è cambiato su Android
  • Verifiche di configurazione nativa che risparmiano tempo in seguito
• Automazione dei rilasci e delle mappe di origine
  • Perché gli upload manuali falliscono nella pratica
  • Un processo di rilascio che funziona effettivamente
  • Un modello di script CI pratico
• Catturare dati di prestazioni e eventi personalizzati
  • Seguire un'interfaccia lenta al posto di indovinare
  • Aggiungere contesto utile agli errori
• Verificare e risolvere il proprio integrazione
  • Attivare eventi di test in modo sicuro
  • Cosa controllare nell'interfaccia di Sentry
  • Problemi di risoluzione comuni di Sentry React Native
• Integrare con flussi di aggiornamento live come Capgo
  • Corrispondere identificatori di rilascio a bundle live

Avviato con SDK

La via più veloce per introdurre Sentry React Native in un nuovo progetto è ancora il wizard di installazione. Gestisce la maggior parte della configurazione ripetitiva e ti porta a una baseline funzionante velocemente. Ciò conta, perché il primo installare manualmente porta spesso a piccoli errori che non noterai fino al primo crash di produzione.

Cosa serve prima dell'installazione

Prima di installare, hai bisogno di un ambiente di sviluppo React Native normale. Hai bisogno di Node, di un gestore di pacchetti, di strumenti di piattaforma per iOS e Android e di Watchman su macOS se già fanno parte del tuo workflow. Hai anche bisogno di un account Sentry e di un progetto creato per React Native.

Se sei ancora valutando se React Native è la scelta operativa giusta per il tuo team, questo Guida per le aziende di React Native fornisce un contesto non di marketing sulle scelte di piattaforma, sulla staffa e sulle aspettative di manutenzione. È utile leggerlo prima di impegnarti nel monitoraggio e nel processo di rilascio di un codice condiviso.

Installa SDK con il wizard dal root del progetto:

npx @sentry/wizard@latest -i reactNative

Il wizard chiede alcune cose che gli sviluppatori cliccano troppo velocemente:

• Scegliere il progettoScegli il progetto Sentry reale che intendi utilizzare in produzione, non un sandbox temporaneo che dimenticherai di aggiornare più tardi.
• Cambiamenti nativiSì, accetta. La cattura degli errori esclusivamente in JavaScript non è sufficiente per le app mobili.
• Caratteristiche facoltativeSì, accetta. Attiva solo le funzionalità che sai di utilizzare, ma non abilitare tutto in modo cieco il giorno di lancio se il tuo team non esaminerà i dati risultanti.

Eseguire il wizard e revisionare il risultato

Dopo che il wizard si è concluso, controlla le modifiche anziché fidarti di loro senza revisione. Dovresti vedere un pacchetto Sentry in package.jsonmodifiche native sotto ios e androidun blocco di inizializzazione nella tua file di ingresso dell'app.

Un inizializzazione tipico assomiglia a questo:

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

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

La DSN indica al SDK dove inviare gli eventi. Trattalo come una configurazione, non come un oggetto di cassaforte che deve essere sempre invisibile. Non è lo stesso di un token di autenticazione. Tuttavia, mantieni la configurazione dell'ambiente pulita e coerente, in modo che la tua app punti al progetto Sentry corretto in ogni ambiente.

A un pattern pratico è caricare il DSN dal configurazione specifica dell'ambiente e inizializzare Sentry prima che il resto della tua app tree si monti. Se stai anche lavorando attraverso la lisciatura di avvio, questa guida a Configurazione dello schermo di avvio React Native is useful because startup code order often intersects with where teams place Sentry initialization.

Regola pratica: inizializzare Sentry il prima possibile nell'avvio dell'app. Se aspetti fino a dopo la navigazione, l'idratazione di autenticazione o la configurazione remota, perderai le fallite di avvio.

A questo stadio, non inseguire la perfezione. L'immediato obiettivo è semplice: lanciare l'app, attivare un'eccezione JavaScript più avanti in questo articolo e confermare che gli eventi raggiungano Sentry. Una volta che funziona, le layer native e di rilascio diventano molto più facili da ragionare.

Configurazione dei Progetti Nativi iOS e Android

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.

Cosa è cambiato su iOS

Apre il progetto iOS e revisiona cosa ha cambiato il wizard. In un'app React Native bare, ciò significa solitamente aggiornamenti intorno all'avvio dell'app e alle fasi di compilazione. Stai cercando le funzioni di inizializzazione di Sentry e i passaggi di caricamento legati al tuo processo di compilazione.

In Xcode, controlla questi luoghi:

• L'avvio dell'applicazione delegato codeLa app richiede l'inizializzazione nativa di Sentry inizialmente durante l'avvio.
• L'elenco delle fasi di costruzioneRicerca di qualsiasi script di caricamento di Sentry relativo alla gestione dei simboli di debug o delle mappe di origine.
• Il comportamento delle impostazioni di costruzione e dell'archiviazioneSi devono generare e rendere disponibili i file dei simboli durante le costruzioni di archiviazione.

Se la tua app utilizza AppDelegate.mml'inizializzazione spesso si trova vicino alla bootstrap del ponte di rete React Native. Il contenuto esatto del file può variare in base alla versione di React Native, al modello e alla presenza dell'architettura nuova, quindi non copiare snippet da repository random a meno che non corrispondano alla forma del tuo progetto.

Ciò che conta è l'intento: i crash di iOS richiedono dati dei simboli nativi e l'app deve iniziare Sentry prima che il crash possa essere osservato in modo affidabile.

Se i crash di iOS appariscono in Sentry con frame nativi non leggibili, il problema solitamente non è "Sentry è rotto." È l'upload dei simboli o la corrispondenza della versione di rilascio.

Cosa è cambiato su Android

L'Android aggiunge spesso modifiche nei file Gradle e a volte nella configurazione a livello di manifesto. Verifica android/build.gradle, android/app/build.gradlee qualsiasi configurazione o connessione di plugin o task correlata a Sentry.

Cose da verificare:

1. Il plugin Sentry Gradle è applicato così gli artefatti di rilascio possono essere elaborati durante il tempo di costruzione.
2. La gestione delle varianti è sana se utilizzi gusti di prodotto o tipi di costruzione multiple.
3. I risultati di ProGuard o R8 sono tenuti in considerazione se i tuoi rilasci riducono o oscurano code.

Un errore comune su Android è supporre che un debug locale riuscito dimostri che la configurazione di rilascio è corretta. Non è vero. La strada del rilascio è diversa, soprattutto quando la minificazione e la firma di CI entrano in scena. Se il tuo team mantiene costruzioni di debug, staging, QA e di magazzino separate, questa suddivisione dei tipi di costruzione mobili è una utile guida per mantenere il comportamento di monitoraggio allineato con ogni variante di costruzione. Verifica del setup nativo che risparmia tempo in seguito

Non fermarti a “il mago ha modificato i file.” Verifica il comportamento direttamente.

Non fermarti a “il mago ha modificato i file.” Verifica il comportamento direttamente.

Ecco il checklist:

• Archivia una build iOS localmente e conferma che la build non fallisce durante il processo di simboli.
• Creare una release build Android e ispeziona i log CI per le attività relative a Sentry.
• Controlla la mappatura del nome del pacchetto e dell'identificatore del bundle in Sentry se gestisci più app sotto un'unica organizzazione.
• Conferma le convenzioni di denominazione delle release adesso, prima che CI inizi a caricare gli artefatti con nomi inconsistenti.

Ecco cosa non funziona bene di solito:

La migliore configurazione è noiosa. Sono presenti gli hook di avvio nativo, i script di costruzione eseguono ogni volta e il nome del rilascio è deterministico per iOS, Android e bundle JavaScript.

Automazione dei rilasci e delle mappe di origine

Se c'è un posto dove le configurazioni di Sentry React Native falliscono, è proprio qui. Le squadre installano il SDK, vedono gli eventi e rimandano l'automazione dei rilasci. Poi arriva la prima seria di problemi di produzione e il tracciato di stack è minificato, il rilascio manca o l'upload della mappa di origine apparteneva a un bundle diverso.

Gli upload manuali delle mappe di origine sembrano accettabili quando si rilascia raramente. In pratica, falliscono perché gli esseri umani sono cattivi nel tenere il conto dei rilasci ripetitivi.

Perché gli upload manuali falliscono in pratica

Il fallimento è prevedibile:

• Qualcuno dimentica di caricare le mappe Dopo una correzione notturna.
• I file caricati appartengono a un commit diverso rispetto alla versione binaria o bundle OTA che gli utenti eseguono.
• Il nome della release cambia leggermente tra iOS, Android e passaggi di CI.
• Si verifica un rebuild dopo l'upload delle mappe e invalida ciò che Sentry dovrebbe essere in grado di riconoscere.

È per questo che non consiglio un approccio "documenta i passaggi in Notion". Funziona fino a quando non viene rilasciata una versione urgente sotto pressione.

Un processo di rilascio che funziona effettivamente

Un setup affidabile ha alcune proprietà:

• Il ID di rilascio viene generato una volta e riutilizzato in ogni parte.
• Il processo di costruzione, di bundle e di caricamento avviene nella stessa pipeline.
• Il file dei mappe di origine viene caricato da CI, non da un laptop del developer.
• L'app inizializza Sentry con la stessa stringa di rilascio che CI ha utilizzato durante il caricamento.

Questo ultimo punto è più importante di quanto comunemente si pensi. Non hai solo bisogno di mappe di origine in Sentry. Hai bisogno di mappe di origine corrette associate all'identificatore di rilascio esatto emesso dall'app durante l'esecuzione.

Se il tuo team sta già standardizzando l'automazione mobile, questo guide all'automazione del processo di costruzione e di rilascio con __CAPGO_KEEP_0__ Actions automatic build and release workflows with GitHub Actions rilevamento errori con React Native e __CAPGO_KEEP_0__

Ambienti di sviluppo CI pratici

Usa uno script come questo in CI e alimenta i valori dal tuo ambiente di pipeline:

#!/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"

Avrai bisogno di adattare il comando di bundle per Android, e molte squadre dividono i compiti specifici per piattaforma al posto di costringere uno script a fare entrambi. È tutto a posto. Ciò che conta è la consistenza.

La disciplina di rilascio vince la scrittura di script astuta. Scegli una convenzione di denominazione, iniettala nell'app durante la compilazione e non lasciare mai che gli upload ad hoc locali competano con CI.

Per React Native, preferisco memorizzare la stringa di rilascio in un'unica posizione di configurazione generata durante la compilazione e leggerla durante Sentry.init():

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

Il payoff è semplice. Quando un evento arriva, Sentry può mappare il frame minificato al code che hai spedito, non al code che pensi di aver spedito.

Cattura dati di prestazioni e eventi personalizzati

Gli errori ti dicono cosa è andato in frantumi. La tracciatura delle prestazioni ti dice cosa i utenti hanno sentito prima di arrendersi.

Un rapporto comune suona così: 'La dashboard è lenta.' Non è abbastanza per debuggare. Lenta dove? Durante la navigazione? Durante il recupero dei dati? Mentre si sta rendendo un grafico pesante? Sentry diventa utile qui quando smetti di trattarlo come un postino di errori e inizi a strumentare il comportamento dell'app.

Seguire una schermata lenta al posto di indovinare

Avvia abilitando la tracciatura delle prestazioni nella tua inizializzazione. La strategia di sampling esatta dipende dal tuo ambiente e dalla tolleranza di volume, ma la struttura assomiglia a questa:

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

Se utilizzi React Navigation, collega l'integrazione in modo che le transizioni di schermo producano dati di traccia. Riproduci poi il reclamo su un dispositivo fisico, non solo su un simulatore. I simulatori nascondono il tipo di lentezza che gli utenti notano.

Esempio di dashboard pratico:

1. Un utente apre la dashboard principale dopo l'accesso.
2. La navigazione si completa, ma il contenuto appare in ritardo.
3. La traccia mostra che la transazione di schermo è lunga.
4. Gli span dei figli rivelano un API richiesta e un percorso di rendering costoso.
5. Ottimizza il percorso di rendering, rilascia nuovamente e confronta la nuova forma della traccia.

Questo è meglio che argomentare con il sentimento.

Per le squadre che pensano in modo ampio alla monitoraggio dei modelli di applicazione web o ibrida, questo articolo sul monitoraggio delle prestazioni nei progetti Capacitor è degno di essere letto perché l'atteggiamento operativo è simile anche se la pila differisce.

Aggiungere un contesto utile agli errori

I dati di prestazione diventano più utili quando gli eventi trasportano un contesto commerciale. Non metadati di vanità. Basta abbastanza per rispondere a chi è stato colpito, su quale schermo si trovava e cosa è successo subito prima del fallimento.

Usa questi strumenti con intenzione:

• Contesto dell'utente con Sentry.setUser() in modo che il supporto possa correlare i rapporti a un account colpito senza dover cercare di indovinare.
• Cronologie degli eventi per azioni come toccare il pulsante Invia, aprire un modulo o avviare una sincronizzazione.
• Etichette personalizzate per dimensioni come tipo di piano, stato della bandiera di feature o API regione.
• Eccezioni catturate con contesto aggiuntivo quando rilanci o metti a fuoco fallimenti controllati.

Esempio:

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

Un percorso di breadcrumb è spesso la differenza tra “l'utente dice che l'app si è congelata” e “l'app si è bloccata dopo l'apertura del dashboard, l'avvio della sincronizzazione e il tentativo di ripetere una richiesta obsoleta.”

Quando l'instrumentazione personalizzata va male, va spesso male perché è troppo rumorosa. Non catturare ogni pressione del pulsante dell'app per sempre. Catturare i confini, le transizioni di stato e le operazioni che contano quando si debugga. Abbastanza contesto per spiegare l'evento. Non troppo per soffocarlo.

Verificare e Risolvere Problemi di Integrazione

Dovresti verificare Sentry prima di distribuire, dopo i cambiamenti del pipeline di costruzione e dopo gli aggiornamenti di SDK. “Funzionava da mesi” non è un test significativo.

La maniera più pulita è attivare fallimenti controllati per entrambe le vie JavaScript e native, poi ispezionare come arrivano in Sentry.

Attivare eventi di test in modo sicuro

Per un errore JavaScript, aggiungi un pulsante temporaneo in una schermata non di produzione:

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

Per un'eccezione catturata che non farà bloccare l'app:

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

La verifica di crash native deve essere fatta con cura e solo in costruzioni di sviluppo o di QA controllate. I metodi di aiuto esatti disponibili possono variare in base alla versione di SDK e alla configurazione del platform, quindi preferisco utilizzare l'utility di crash test nativa documentata di SDK quando presente piuttosto che inventare il proprio percorso di crash.

Cosa controllare nell'interfaccia di Sentry

Quando l'evento compare, ispeziona più del titolo.

Controlla questi campi:

• Piattaforma e meccanismoCiò aiuta a distinguere le eccezioni JS dalle crash native.
• Rilascio e distSe sono vuoti o sbagliati, i mappe di origine e la simbolizzazione si allontaneranno.
• Frame di pilaLe posizioni di origine leggibili dovrebbero apparire per le mappe JavaScript caricate correttamente.
• Breadcrumb e tagConferma che il contesto personalizzato sia arrivato.
• AmbienteAssicurati che gli eventi di sviluppo e di produzione non siano mescolati in un flusso unico.

Se un evento nativo arriva ma ha una simbolizzazione scarsa, non continuare a modificare l'app code. Questo è spesso un problema di artefatto di build.

Troubleshooting React Native comune Sentry

Un'abitudine finale che si rivela utile è mantenere una piccola

Integrating with Live Update Workflows like Capgo

nel processo di rilascio. Attiva un evento JS in staging, conferma i valori di rilascio e verifica le posizioni di origine prima di promuovere una build

Integrare con flussi di lavoro di aggiornamento in tempo reale come __CAPGO_KEEP_0__ Gli aggiornamenti in tempo reale modificano il modello di rilascio. Il binario nel negozio potrebbe rimanere lo stesso mentre il pacchetto JavaScript cambia sotto di esso. Se Sentry pensa ancora in termini dell'applicazione originale, le tracce di stack diventano fuorvianti velocementeLa soluzione è far seguire all'identità di rilascio di Sentry

il pacchetto JavaScript in tempo reale, non solo il binario nativo

Corrispondenza degli identificatori di rilascio ai pacchetti in tempo reale release Per i flussi di lavoro di aggiornamento in tempo reale, trattare dist e

context

• Utilizza la versione dell'app nativa come parte del nome di rilascio di base.
• Aggiungi la versione di aggiornamento in tempo reale o l'identificatore del pacchetto.
• Utilizza dist per la differenziazione del canale o della build quando si adatta al tuo modello.
• Carica i mappe di origine per ogni bundle in tempo reale sotto l'identificatore di rilascio esatto.

Esempio: se il tuo app carica i metadati di aggiornamento al avvio, inizializza Sentry con valori derivati dal bundle attualmente attivo, non solo dalla configurazione di build statica.

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

In questo modo, quando un utente incontra un errore su un bundle aggiornato in tempo reale, Sentry risolve i frame contro la mappa di origine per quel hotfix anziché il vecchio bundle di archiviazione.

Questo è importante con qualsiasi flusso di lavoro di tipo OTA. Se desideri una buona introduzione alle componenti in movimento dietro quel modello di consegna, questa spiegazione di come funzionano gli aggiornamenti in tempo reale negli app Capacitor è una buona riferenza.

Ecco il tipo di vista operativa che le squadre mirano a raggiungere quando combinano i metadati di aggiornamento con la tracciatura dei rilasci:

La principale cosa da evitare è riutilizzare una stringa di rilascio statica per ogni aggiornamento post-archiviazione. Se più bundle condividono la stessa rilascio Sentry, il debugging si trasforma nuovamente in un gioco di indovinello.

Se il tuo team invia correzioni fuori dal ciclo di revisione degli store app Capgo is worth evaluating. It gives Capacitor teams a structured way to deliver live updates, target channels, control rollouts, and recover from bad releases quickly. Pair that with disciplined Sentry release naming and source map uploads, and you get a workflow where errors still point to the exact code users are running.