Sentry React Native: Guida di 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 facileLa parte dolorosa arriva più tardi: integrazione nativa, simbolizzazione, mappe di origine, denominazione delle versioni di rilascio e mantenimento di tutto ciò in linea 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 di App Store, rilasci Android e pacchetti JavaScript che non sempre provengono dal binario originale.

Indice dei contenuti

• Avvio con Sentry SDK
  • Cosa serve prima di installare
  • Eseguire il wizard e revisionare il risultato
• Configurazione dei progetti nativi iOS e Android
  • Cosa è cambiato su iOS
  • Cosa è cambiato su Android
  • Verifiche di setup nativo 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 screen lento al posto di indovinare
  • Aggiungere un 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 ai bundle live

Avvio con il 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 linea di base funzionante velocemente. Ciò conta, perché il primo installare manualmente porta spesso a piccole incoerenze che non noterai fino al primo crash in produzione.

Ciò di cui hai bisogno prima di installare

Ti serve un ambiente di sviluppo React Native normale prima. Node, un gestore di pacchetti, strumenti di piattaforma per iOS e Android, e Watchman su macOS se già fa 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 imprese di React Native fornisce un contesto non di marketing sulle scelte di piattaforma, la staffazione e le aspettative di manutenzione. È utile leggerlo prima di impegnare il monitoraggio e il processo di rilascio in un codice condiviso.

Installa il 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 progetto. Scegli il progetto Sentry reale che intendi utilizzare in produzione, non un sandbox temporaneo che dimenticherai di aggiornare più tardi.
• Modifiche nativeSì, 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 è completato, controlla le modifiche anziché fidarti di loro senza revisione. Dovresti vedere un pacchetto Sentry in package.jsone modifiche native sotto ios e androide un blocco di inizializzazione nel file di ingresso dell'applicazione.

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 sicurezza che deve essere sempre nascosto. Non è lo stesso di un token di autenticazione. Tuttavia, mantieni la configurazione dell'ambiente pulita e coerente, in modo che l'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 tree di app si monti. Se sei anche al lavoro per 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 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 raggiungono 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 il wizard ha cambiato. In un'app React Native nuda, ciò significa solitamente aggiornamenti intorno all'avvio dell'app e alle fasi di costruzione. Stai cercando le funzioni di inizializzazione di Sentry e i passaggi di caricamento legati al tuo processo di costruzione.

In Xcode, controlla questi luoghi:

• L'avvio dell'applicazione delegato codeLa app richiede l'inizializzazione nativa di Sentry in fase di avvio precoce.
• L'elenco delle fasi di costruzioneRicerca di qualsiasi script di caricamento Sentry relativo ai simboli di debug o alla gestione dei 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 vicina al bootstrapping della passerella 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 iOS richiedono dati dei simboli, e l'app deve avviare Sentry prima che il crash possa essere osservato in modo affidabile.

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

Ciò che è cambiato su Android

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

Le cose da verificare:

1. È applicato il plugin Sentry Gradle così gli artefatti di rilascio possono essere elaborati durante il tempo di costruzione.
2. La gestione delle varianti è sana se si utilizzano i flavor dei prodotti o i tipi di costruzione multiple.
3. Le uscite di ProGuard o R8 sono tenute in conto se i 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 di rilascio è diversa, soprattutto quando la minificazione e la firma di CI entrano in gioco. Se il tuo team mantiene costruzioni di debug, staging, QA e store separate, questa suddivisione dei tipi di costruzione mobili è un riferimento utile 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.

Tipi di costruzione mobili

Usa questa checklist:

• Archivia una build iOS localmente e conferma che la build non fallisce durante il trattamento dei simboli.
• Crea una build di rilascio Android e ispeziona i log CI per le attività relative a Sentry.
• Controlla la mappatura del nome del pacchetto e dell'identificatore di 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. Le hook di avvio nativo sono in posto, i script di costruzione si 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 cadono a pezzi, è 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 della pila è 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 mantenimento dei libri di rilascio ripetitivi.

Perché gli upload manuali falliscono in pratica

Il fallimento è prevedibile:

• Qualcuno dimentica di caricare le mappe Dopo una correzione notturna.
• Le 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 i passaggi iOS, Android e CI.
• Si verifica un rebuild dopo l'upload delle mappe e invalida ciò che Sentry dovrebbe essere in grado di corrispondere.

È per questo che non consiglio un approccio "documenta i passaggi in Notion". Funziona fino a quando non esce una release 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, bundle e caricamento avviene nella stessa pipeline.
• Il file dei mappe di origine viene caricato da CIe 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 si possa pensare. Non hai solo bisogno di mappe di origine in Sentry. Hai bisogno di mappe di origine corrette associate all'ID 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 rilascio con __CAPGO_KEEP_0__ Actions automatic build and release workflows with GitHub Actions Il rilascio ID viene generato una volta e riutilizzato in ogni parte.

Ambienti di integrazione pratici

Utilizza uno script come questo nell'ambiente di integrazione 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 coerenza.

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

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 inviato, non al code che pensi di aver inviato.

Captura di dati di prestazioni e eventi personalizzati

Gli errori ti dicono cosa è andato in frantumi. La tracciatura di 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 in-box degli errori e inizi a strumentare il comportamento dell'applicazione.

Tracciare 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 figli rivelano un richiesta API 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 webview 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

Il dato di prestazione diventa più utile quando gli eventi trasportano un contesto commerciale. Non i dati di metadata vanitosi. Basta abbastanza per rispondere a chi era stato colpito, su quale schermo si trovava e cosa era accaduto subito prima del fallimento.

Usa questi strumenti con intenzione:

• Contesto dell'utente con Sentry.setUser() così il supporto può correlare i rapporti a un account colpito senza dover cercare di capire.
• Panini per azioni come toccare il pulsante Invia, aprire un modulo o avviare un 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 è bloccata” e “l'app si è bloccata dopo l'apertura del dashboard, l'avvio della sincronizzazione e il riprovo di una richiesta obsoleta.”

Quando l'instrumentazione personalizzata va male, va spesso male perché è troppo rumorosa. Non catturare ogni pressione del pulsante nell'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 è quella di 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 test di crash nativa documentata di SDK quando presente piuttosto che inventare il proprio percorso di crash.

Cosa controllare nell'interfaccia di Sentry

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

Controlla questi campi:

• Piattaforma e meccanismo. Ciò aiuta a distinguere le eccezioni JS dalle crash native.
• Rilascio e dist. Se sono vuoti o sbagliati, i mappe di origine e la simbolizzazione si allontaneranno.
• Frame di pila. Le localizzazioni di origine leggibili dovrebbero apparire per le mappe JavaScript caricate correttamente.
• Panini e tag. Conferma che il tuo contesto personalizzato sia arrivato.
• Ambiente. Assicurati che gli eventi di sviluppo e di produzione non siano mescolati in un flusso unico.

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

Troubleshooting comune di Sentry React Native

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

contexto: Pagina/area: Sito web di marketing Capgo. Ruolo: Etichetta di navigazione breve o elemento UI. Visualizzato in: pagina trust.astro. Chiave di messaggio `e` (E).

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

Ad esempio, se il tuo app carica i metadati di aggiornamento al startup, 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 hotfixato, Sentry risolve i frame contro la mappa di origine per quel hotfix invece della vecchia bundle di archiviazione.

Questo è importante con qualsiasi workflow 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:

Evitare il principale errore è 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 per l'applicazione 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.