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 l'installazione base è la parte facile. I parti dolorosi arrivano più tardi: integrazione nativa, simbolizzazione, mappe di origine, denominazione di rilascio e mantenimento di tutto ciò 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 di App Store, rilasci Android e pacchetti JavaScript che non sempre provengono dal binario originale.

Indice

• Avvio rapido con il 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 configurazione native 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 lo screen lento al posto di indovinare
  • Aggiungere contesto utile agli errori
• Verificare e risolvere il problema della tua integrazione
  • Attivare eventi di test in modo sicuro
  • Cosa controllare nell'interfaccia utente di Sentry
  • Troubleshooting comune di Sentry React Native
• Integrare con flussi di aggiornamento in tempo reale come Capgo
  • Corrispondere identificatori di rilascio ai bundle live

Avviare la procedura con il Sentry SDK

La via più veloce per ottenere Sentry React Native in una nuova app è 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 di installare

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à parte del tuo workflow. Inoltre, serve un account Sentry e un progetto creato per React Native.

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

Installa il SDK con il wizard dalla radice 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 nativi. Sì, assicurati. La cattura degli errori esclusivamente in JavaScript non è sufficiente per le app mobili.
• Caratteristiche facoltative. Attiva solo le funzionalità che sai di utilizzare, ma non abilita 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 invece di fidarti di loro senza revisione. Dovresti vedere un pacchetto Sentry in package.json, modifiche native sotto ios e android, e un blocco di inizializzazione nel file di ingresso dell'applicazione.

Un inizializzazione tipica assomiglia a questo:

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

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

Il DSN indica al SDK dove inviare gli eventi. Trattalo come una configurazione, non come un oggetto di cassaforte che deve mai essere visibile. Non è lo stesso di un token di autenticazione. Comunque, mantieni la configurazione dell'ambiente pulita e coerente affinché l'app punti al progetto Sentry giusto in ogni ambiente.

A un pattern pratico è caricare il DSN da configurazioni specifiche dell'ambiente e inizializzare Sentry prima che il resto della tua app tree monti. Se stai anche lavorando sulla lisciatura di avvio, questa guida al setup dello schermo di avvio React Native è utile perché l'ordine di avvio spesso interessa con dove le squadre collocano l'inizializzazione di Sentry. Configurazione dello schermo di avvio React Native is useful because startup code order often intersects with where teams place Sentry initialization.

Inizializza Sentry il prima possibile durante l'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 fasi native e di rilascio diventano molto più facili da ragionare.

Configurazione dei Progetti Nativi iOS e Android

A questo stadio, molte squadre React Native hanno una falsa sensazione di completamento. Il JavaScript è installato, gli eventi si mostrano e tutti si assumono che il reporting degli incidenti sia fatto. Non è vero. Se l'integrazione nativa è disattivata, alcuni degli incidenti che ti preoccupano di più non raggiungeranno mai Sentry in una forma utilizzabile.

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.

Apre il progetto iOS e verifica 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 le fasi di caricamento legate al tuo processo di costruzione.

In Xcode, controlla questi luoghi:

Avvio dell'applicazione delegato __CAPGO_KEEP_0__

• Avvio dell'app code. L'app necessita di un inizializzazione nativa di Sentry presto all'avvio.
• Build Phases. Cerca qualsiasi script di invio di Sentry relativo ai simboli di debug o alla gestione dei mappe di origine.
• Impostazioni di costruzione e comportamento dell'archivio. I file simbolici devono essere generati e disponibili durante le costruzioni dell'archivio.

Se l'app utilizza AppDelegate.mm, l'inizializzazione spesso si trova vicino alla bootstrap del ponte di React Native. Il contenuto esatto del file può variare in base alla versione di React Native, al template 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 nativi richiedono dati simbolici, 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.

Cosa è cambiato su Android

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

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 utilizzi i flavor di prodotto o più tipi di costruzione.
3. Le uscite di ProGuard o R8 sono tenute in conto 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 è così. 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 direttamente il comportamento

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

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 oraprima che CI inizi a caricare gli artefatti con nomi non coerenti.

Ecco cosa non funziona bene di solito:

La migliore configurazione è noiosa. Sono presenti gli hook di avvio nativi, 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, è 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 lo stack trace è 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 patch notturna.
• I file caricati appartengono a un commit diverso rispetto alla versione binaria o bundle OTA utilizzato dagli utenti.
• Il nome della release cambia leggermente tra iOS, Android e passaggi CI.
• Si verifica un rebuild dopo l'upload delle mappe e invalida ciò che Sentry dovrebbe essere associato.

È 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 effettivamente tiene

Un setup affidabile ha alcune proprietà:

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

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

Se il tuo team sta già standardizzando l'automazione mobile, questa guida all'automazione del flusso di lavoro di rilascio e di costruzione con __CAPGO_KEEP_0__ Actions automatic build and release workflows with GitHub Actions fits well with the same operational model.

A pattern di script CI pratico

Usa un script come questo in CI e alimenta i valori dai tuoi ambienti 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 lavori specifici per piattaforma invece di costringere uno script a fare entrambi. È tutto a posto. Ciò che conta è la consistenza.

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

Per React Native, preferisco memorizzare la stringa di rilascio in una posizione di configurazione generata durante l'elaborazione 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.

Captura dei dati di prestazioni e eventi personalizzati

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

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

Tracciare una schermata lenta invece di indovinare

Inizia 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 pratica:

1. Un utente apre la dashboard principale dopo l'accesso.
2. La navigazione è completa, ma il contenuto appare in ritardo.
3. La traccia mostra che la transazione di schermo è lunga.
4. Gli span 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.

Meglio di discutere sulla base del sentimento.

Per le squadre che pensano in modo ampio alla monitoraggio dei modelli di applicazione web o ibrida, questo articolo su il 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 aziendale. Non i dati 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() così il supporto può correlare i rapporti a un account colpito senza dover scavare attraverso congetture.
• Panini per azioni come toccare submit, 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 rendi visibili 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 è fallita dopo l'apertura del dashboard, l'avvio della sincronizzazione e il tentativo di una richiesta obsoleta.”

Quando l'instrumentazione personalizzata va male, di solito va 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.

Verifica e Risoluzione dei Problemi della Tua Integrazione

Verifica 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, quindi ispeziona come arrivano in Sentry.

Attivazione di 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à cadere l'app:

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

La verifica dei crash nativi 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 del SDK quando presente piuttosto che inventare il proprio percorso di crash.

Cosa controllare nell'interfaccia utente di Sentry

Quando l'evento compare, 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. Dovrebbero apparire le posizioni di origine leggibili per le mappe JavaScript caricate correttamente.
• Breadcrumb e tag. Conferma che il contesto personalizzato sia arrivato.
• Ambiente. Assicurati che gli eventi di sviluppo e produzione non siano mescolati in un flusso unico.

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

Risolvere i Problemi Comuni con 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

Integrazione con Flussi 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 presto fuorviantiLa 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 aggiornamento in tempo reale, trattare dist e

come identificatori di runtime legati al pacchetto JavaScript consegnato. La versione dell'app nativa ancora conta, ma non è sufficiente da sola una volta che i pacchetti possono cambiare indipendentemente. Un modello pratico potrebbe assomigliare a questo:

• Utilizza la versione dell'app nativa come parte del nome della versione 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 quel identificatore di rilascio esatto.

Ad esempio, se il tuo app carica i metadati di aggiornamento all'avvio, inizializza Sentry con valori derivati dal bundle attualmente attivo, non solo dalla configurazione di costruzione statica.

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

In questo modo, quando un utente colpisce 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 conta 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 riferimento.

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

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

Se il tuo team invia correzioni fuori dal ciclo di revisione degli store di app, Capgo è utile valutare. Dà ai team di Capacitor una struttura per consegnare aggiornamenti in tempo reale, targetizzare i canali, controllare le distribuzioni e riprendersi rapidamente da rilasci dannosi. Uniscilo a una disciplinata denominazione delle versioni di Sentry e caricamenti di mappe di origine, e ottieni un flusso di lavoro in cui gli errori puntano ancora ai code esatti utenti che stanno eseguendo.