Sentry React Native : Guide d'intégration 2026

Vous avez un application React Native qui fonctionne localement, la QA a validé, et la production est proche. Alors la question évidente arrive : ce qui se passe quand elle se casse sur un appareil utilisateur ?

Sans Sentry, la réponse est généralement mauvaise. Vous obtenez un ticket de support, un écran vague, peut-être un journal de console d'une build de dev qui ne correspond pas à la production. Avec Sentry React Native configuré correctement, vous obtenez l'erreur, la pile, la version qui l'a déployée, et suffisamment de contexte pour la réparer sans deviner. Le hic est que Installation de base est la partie facileLa partie douloureuse commence ensuite : l'intégration native, la symbolisation, les cartes de sources, la nomination des versions de sortie, et garder tout cela aligné lorsque votre modèle de livraison inclut des mises à jour en temps réel.

La plupart des guides s'arrêtent trop tôt. Un réel setup doit survivre aux CI, aux builds de l'App Store, aux sorties Android et aux bundles JavaScript qui ne viennent pas toujours du binôme d'origine.

Table des matières

• Prise en main avec Sentry SDK
  • Ce dont vous avez besoin avant l'installation
  • Exécution du guide et examen du résultat
• Configuration des projets iOS et Android natifs
  • Ce qui a changé sur iOS
  • Ce qui a changé sur Android
  • Contrôles de setup natif qui économisent du temps plus tard
• Automatisation des sorties et des cartes de sources
  • Pourquoi les téléchargements manuels échouent en pratique
  • Un processus de mise en production qui tient vraiment
  • Un modèle de script CI pratique
• Capturer des données de performance et des événements personnalisés
  • Suivre les traces d'une écran lent au lieu de deviner
  • Ajouter un contexte utile aux erreurs
• Vérifier et dépanner votre intégration
  • Déclencher des événements de test de manière sécurisée
  • Quels éléments vérifier dans l'interface utilisateur de Sentry
  • Les problèmes de dépannage React Native Sentry courants
• Intégrer avec des workflows de mise à jour en direct comme Capgo
  • Correspondre les identifiants de version à des lots en direct

Prise en main de SDK

La meilleure façon de mettre en place Sentry React Native dans une nouvelle application est toujours le guide d'installation. Il gère la plupart de la configuration répétitive et vous amène rapidement à une base de travail fonctionnelle. Cela compte, car la mise en place manuelle de la première installation conduit souvent à des petites incohérences que vous ne remarquez pas jusqu'au premier crash en production.

Ce dont vous avez besoin avant l'installation

Vous avez besoin d'un environnement de développement React Normal en premier lieu. Node, un gestionnaire de packages, des outils de plateforme pour iOS et Android, et Watchman sur macOS si cela fait déjà partie de votre flux de travail. Vous avez également besoin d'un compte Sentry et d'un projet créé pour React Native.

Si vous évaluez toujours si React Native est le choix opérationnel approprié pour votre équipe, ce Guide React Native pour les entreprises apporte un contexte non commercial utile autour des compromis de plateforme, de personnel et d'attentes de maintenance. Il est recommandé de le lire avant de vous engager dans le suivi de votre processus de mise en production autour d'un code partagé.

Installez SDK avec le guide d'installation depuis la racine du projet :

npx @sentry/wizard@latest -i reactNative

Le guide demande quelques choses que les développeurs cliquent trop rapidement :

• Sélection de projetChoisissez le projet Sentry réel que vous prévoyez utiliser en production, et non un sandbox temporaire que vous oublierez de mettre à jour ultérieurement.
• Changements natifs. Dit oui. La capture d'erreurs uniquement en JavaScript n'est pas suffisante pour les applications mobiles.
• Fonctionnalités optionnelles. Activez uniquement les fonctionnalités que vous savez utiliser, mais ne les activez pas toutes sans réfléchir si votre équipe ne passera pas en revue les données résultantes.

Exécution du guide et examen des résultats

Après la fin du guide, inspectez les modifications au lieu de les accepter sans examen. Vous devriez voir un paquet Sentry dans package.jsonchangements natifs sous ios et androidun bloc d'initialisation dans votre fichier d'entrée d'application.

Une initialisation typique ressemble à ceci :

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

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

Le DSN indique au SDK où envoyer les événements. Traitez-le comme une configuration, et non comme un coffre-fort qui doit rester invisible. Ce n'est pas la même chose qu'un jeton d'authentification. Cependant, assurez-vous que votre environnement soit propre et cohérent, afin que votre application pointe vers le bon projet Sentry dans chaque environnement.

A un stade pratique, il est recommandé de charger la DSN à partir de la configuration spécifique à l'environnement et d'initialiser Sentry avant que le reste de l'arborescence de votre application ne soit monté. Si vous travaillez également sur la mise en forme de l'initialisation, ce guide sur la mise en place de l'écran de splash de React Native est utile car l'ordre d'initialisation de l'application au démarrage souvent se chevauche avec où les équipes placeraient l'initialisation de Sentry. La mise en place de l'écran de splash de React Native is useful because startup code order often intersects with where teams place Sentry initialization.

À ce stade, ne poursuivez pas la perfection. L'objectif immédiat est simple : lancer l'application, déclencher une exception JavaScript plus tard dans l'article et confirmer que les événements atteignent Sentry. Une fois cela fonctionnel, les couches natives et de version deviennent beaucoup plus faciles à raisonner. La configuration des projets natifs iOS et Android

À ce stade, de nombreux équipes de React Native ont une fausse impression de complétion. Le JavaScript est installé, les événements apparaissent et tout le monde suppose que la mise en place de la détection des crashs est terminée. Ce n'est pas le cas. Si l'intégration native est désactivée, certaines des défaillances que vous craignez le plus ne parviendront jamais à Sentry sous une forme utilisable.

Ce qui a changé sur iOS

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.

Dans Xcode, vérifiez ces endroits :

Le démarrage de l'application dans le délégué d'application

__CAPGO_KEEP_0__

• codeLa mise en route de Sentry native est nécessaire tôt dans la lancement de l'application.
• Phases de constructionRecherchez tout script d'envoi de Sentry lié à la gestion des symboles de débogage ou des cartes de sources.
• Paramètres de construction et comportement d'archiveLes fichiers de symboles doivent être générés et disponibles pendant les builds d'archive.

Si votre application utilise AppDelegate.mml'initialisation de Sentry se trouve souvent près de l'initialisation de la passerelle React Native. Le contenu du fichier peut varier en fonction de la version de React Native, du modèl’et de l'utilisation de la nouvelle architecture, n'importe donc pas les snippets de fichiers de random repos à moins qu'ils correspondent à la forme de votre projet.

C'est l'intention qui compte : les crashes iOS natives nécessitent des données de symboles, et l'application doit démarrer Sentry avant que les crashes ne puissent être observés de manière fiable.

Si les crashes iOS apparaissent dans Sentry avec des cadres natifs non lisible, le problème est généralement « Sentry n'est pas cassé ». C'est l'envoi de symboles ou la correspondance de la version.

Ce qui a changé sur Android

Android ajoute généralement des modifications dans les fichiers Gradle et parfois des configurations au niveau du manifest. Vérifiez android/build.gradle, android/app/build.gradleet toute configuration ou tâche liée à Sentry.

Les choses à vérifier :

1. Le plugin Sentry Gradle est appliqué afin que les artefacts de version puissent être traités pendant le temps de build.
2. La gestion des variantes est saine si vous utilisez des saveurs de produit ou plusieurs types de build.
3. Les sorties ProGuard ou R8 sont prises en compte si vos builds de version réduisent ou obfusquent code.

Une erreur commune sur Android est de supposer que l'exécution de debug locale réussie prouve que la configuration de version est correcte. Ce n'est pas le cas. La voie de version est différente, surtout une fois que la minification et la signature de CI entrent en jeu. Si votre équipe maintient des builds de debug, de pré-production, de QA et de magasin séparés, ce décompte des types de build mobiles est un référentiel utile pour maintenir le comportement de suivi aligné sur chaque variante de build. Les vérifications de configuration natives qui économisent du temps plus tard

Ne vous arrêtez pas à « le wizard a modifié des fichiers ». Vérifiez le comportement directement.

mobile build types

Utilisez cette liste de vérification :

• Archiver une build iOS localement et confirmer que la build ne faille pas pendant le traitement des symboles.
• Créer une build de release Android et inspecter les journaux CI pour les tâches liées à Sentry.
• Vérifier la correspondance entre le nom de package et l'identifiant de bundle dans Sentry si vous gérez plusieurs applications sous une même organisation.
• Confirmer les conventions de nommage des releases maintenant, avant que CI commence à télécharger des artefacts sous des noms incohérents.

Voici ce qui ne fonctionne généralement pas bien :

La meilleure configuration est ennuyeuse. Les appels de démarrage natifs sont en place, les scripts de construction s'exécutent chaque fois, et les noms de version sont déterministes sur iOS, Android et les bundles JavaScript.

Automatiser les versions et les cartes de sources

Si un seul endroit où les configurations de Sentry React Native se défont, c'est ici. Les équipes installent le SDK, voient des événements, et retardent l'automatisation des versions.

Les uploads manuels de cartes de sources semblent acceptables lorsque vous expédiez rarement. En pratique, ils échouent car les humains sont mauvais pour le bookkeeping des versions répétitives.

Pourquoi les uploads manuels échouent en pratique

Les modes de failure sont prévisibles :

• Quelqu'un oublie de télécharger les cartes après une mise à jour de dernière minute.
• Les fichiers téléchargés appartiennent à un commit différent que le paquet ou le bundle OTA utilisé par les utilisateurs.
• Le nom de la version change légèrement entre les étapes iOS, Android et CI.
• Une reconstruction a lieu après téléchargement de cartes et invalide ce que Sentry devrait correspondre.

C'est pourquoi je ne recommande pas une approche « documenter les étapes dans Notion ».

Un diagramme à sept étapes illustrant le processus automatisé de gestion des versions Sentry et des cartes de sources pour React Native.

Un processus de versionnement qui tient vraiment la route : un setup fiable a quelques propriétés :

• Les identifiants de version sont générés une fois et réutilisés partout.
• Les étapes de construction, de mise en bundle et d'upload se produisent dans le même pipeline.
• Les cartes de source sont uploadées à partir de CI, et non à partir d'un ordinateur portable de développeur.
• L'application initialise Sentry avec la même chaîne de version que CI utilisée lors de l'upload. Ce dernier point compte plus que l'on ne le pense généralement. Vous n'avez pas besoin uniquement de cartes de source dans Sentry. Vous avez besoin

des cartes de source correctes attachées à l'identifiant de version exactement émis par l'application en temps de exécution Si votre équipe standardise déjà l'automatisation mobile, ce guide à l'automatisation de la construction et des flux de version avec __CAPGO_KEEP_0__ Actions.

se conforme bien au même modèl’opérationnel. GitHub __CAPGO_KEEP_0__

Au sujet d'un modèle de script CI pratique

Utilisez un script comme celui-ci dans CI et alimentez les valeurs à partir de votre environnement de 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"

Vous devrez adapter la commande de paquetage pour Android, et de nombreuses équipes séparent les tâches spécifiques aux plateformes au lieu de forcer un script à faire les deux. C'est tout à fait acceptable. Ce qui compte, c'est la cohérence.

La discipline de la mise en production l'emporte sur la mise en œuvre ingénieuse. Choisissez une convention de nommage, injectez-la dans l'application lors de la génération du build et n'autorisez jamais les téléchargements locaux ad hoc à concurrencer CI.

Pour React Native, j'ai préféré stocker la chaîne de mise en production dans une localisation de configuration générée par le build et la lire pendant Sentry.init():

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

Le gain est simple. Lorsqu'un événement arrive, Sentry peut mapper le cadre minifié vers la code que vous avez expédiée, et non vers la code que vous pensez avoir expédiée.

Capturer des données de performance et des événements personnalisés

Les plantages vous disent ce qui a cassé. La traçabilité de performance vous dit ce que les utilisateurs ont ressenti avant de renoncer.

Un rapport commun ressemble à ceci : « Le tableau de bord est lent. » Ce n'est pas suffisant pour déboguer. Lent où ? Pendant la navigation ? Lors de la récupération de données ? Lors de la mise en page d'un graphique lourd ? Sentry devient utile ici lorsque vous cessez de traiter cela comme un boîtier d'erreurs et que vous commencez à instrumenter le comportement de l'application.

Suivre la traçabilité d'une écran lent au lieu de deviner

Commencez par activer la traçabilité de performances dans votre initialisation. La stratégie d'échantillonnage exacte dépend de votre environnement et de votre tolérance de volume, mais la structure ressemble à ceci :

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

Si vous utilisez React Navigation, reliez l'intégration de sorte que les transitions d'écran produisent des données de traçage. Répétez ensuite le problème sur un appareil physique, et non juste sur un simulateur. Les simulateurs masquent le type de lenteur que les utilisateurs remarquent.

Un exemple de tableau de bord pratique :

1. Un utilisateur ouvre le tableau de bord principal après connexion.
2. La navigation est terminée, mais le contenu apparaît en retard.
3. La trace montre que la transaction d'écran est longue.
4. Les sous-espaces révèlent une requête API et un chemin de rendu coûteux.
5. Vous optimisez le chemin de rendu, vous expédiez à nouveau, et vous comparez la nouvelle forme de la trace.

C'est mieux que d'argumenter sur la base de sentiments.

Pour les équipes qui réfléchissent de manière large sur les modèles de surveillance de webview ou d'applications hybrides, cet article sur la surveillance de performances dans les projets __CAPGO_KEEP_0__ performance monitoring in Capacitor projects Start by enabling performance tracing in your initialization. The exact sampling strategy depends on your environment and volume tolerance, but the structure looks like this:

Ajouter un contexte utile aux erreurs

Les données de performance deviennent plus utiles lorsque les événements comportent un contexte commercial. Pas de métadonnées vaniteuses. Juste assez pour répondre à qui a été affecté, sur quelle page ils se trouvaient, et ce qui s'est passé juste avant le dysfonctionnement.

Utilisez ces outils avec intention :

• Contexte de l'utilisateur avec Sentry.setUser() afin que le support puisse corriger les rapports à un compte affecté sans passer par des suppositions.
• Les miettes pour les actions comme appuyer sur le bouton soumettre, ouvrir un modal, ou démarrer une synchronisation.
• Les balises personnalisées pour des dimensions comme le type de plan, l'état de la bannière de fonctionnalité, ou API région.
• Les exceptions capturées avec un contexte supplémentaire lorsque vous riez et rejetez ou faites surface à des dysfonctionnements contrôlés.

Exemple :

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 chemin de navigation est souvent la différence entre « l'application s'est bloquée » et « l'application a échoué après l'ouverture du tableau de bord, le démarrage de la synchronisation et la réessai d'une requête obsolète. »

Lorsque l'instrumentation personnalisée se trompe, elle se trompe généralement en étant trop bruyante. Ne capturez pas chaque appui sur le bouton dans l'application à tout jamais. Capturer les limites, les transitions d'état et les opérations qui comptent lors de la débogage. Assez de contexte pour expliquer l'événement. Pas assez pour l'étouffer.

Vérifier et Dépanner votre Intégration

Vous devriez vérifier Sentry avant de lancer, après les modifications de la chaîne de pipeline de construction, et après les mises à jour de SDK. « Cela fonctionnait il y a des mois » n'est pas un test significatif.

La méthode la plus propre est de déclencher des échecs contrôlés pour les deux chemins JavaScript et natifs, puis inspecter comment ils arrivent dans Sentry.

Déclencher des événements de test de manière sûre

Pour une erreur JavaScript, ajoutez un bouton temporaire dans une écran non de production :

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

Pour une exception capturée qui ne fera pas tomber l'application :

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

Le test de crash natif doit être effectué avec soin et uniquement dans les builds de développement ou de QA contrôlés. Les méthodes d'aide exactes disponibles peuvent varier en fonction de la version de SDK et de la mise en œuvre de la plateforme, donc je préfère utiliser la méthode de test de crash native documentée de SDK lorsqu'elle est disponible plutôt que d'inventer mon propre chemin de crash.

Ce que vérifier dans l'interface utilisateur de Sentry

Lorsque l'événement apparaît, inspectez plus que le titre.

Vérifiez ces champs :

• Plateforme et mécanisme Ceci aide à distinguer les exceptions JS des crashes natifs.
• Version et dist Si elles sont vides ou incorrectes, les cartes de sources et la symbolication dériveront.
• Champ de pile Les emplacements de source lisibles devraient apparaître pour les cartes JavaScript correctement chargées.
• Briques de navigation et étiquettes Confirmez que votre contexte personnalisé est arrivé.
• Environnement Assurez-vous que les événements de développement et de production ne sont pas mélangés dans un flux.

Si un événement natif arrive mais a une symbolisation médiocre, ne continuez pas à ajuster l'application code. C'est généralement un problème d'artefact de build.

Problèmes courants de dépannage de Sentry React Native

Un dernier habitude qui rapporte est de garder une petite « liste de vérification de test de fumée de monitoring » dans votre processus de publication. Déclenchez un événement JS en phase de test, confirmez les valeurs de publication et vérifiez les emplacements de source avant de promouvoir une build

Intégrer avec les workflows d'actualisation en direct comme Capgo

Les mises à jour en direct changent le modèle de publication. Le fichier binaire dans la boutique peut rester le même tandis que le paquet JavaScript change sous lui. Si Sentry pense toujours en termes de version d'application originale, les traces de pile deviennent trompeuses rapidement

La solution est de faire en sorte que l'identité de publication de Sentry suive le paquet de mise à jour en direct et non seulement le fichier binaire natifCorrespondance des identifiants de publication aux paquets de mise à jour en direct

Pour les workflows d'actualisation en direct, traitez

et release context : Page/zone : Site web de marketing Capgo. Rôle : Étiquette de navigation ou élément UI court. Vu dans : page trust.astro. Clé de message `et` (Et) dist comme des identifiants de runtime liés au paquet JavaScript délivré. La version de l'application native compte toujours, mais elle ne suffit pas seule une fois que les paquets peuvent changer indépendamment

Un modèle pratique ressemble à ceci :

• Utilisez la version de l'application native en tant que partie du nom de la version de base.
• Ajoutez la version de mise à jour en direct ou l'identifiant du package.
• Utilisez dist pour la différenciation spécifique au canal ou à la construction lorsque cela convient à votre modèle.
• Téléchargez les cartes de source pour chaque bundle en direct sous cet identifiant de version exacte.

Par exemple, si votre application charge les métadonnées de mise à jour au démarrage, initialisez Sentry avec des valeurs dérivées du bundle actif en cours, et non seulement à partir de la configuration de construction statique.

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

De cette façon, lorsque l'utilisateur rencontre une erreur sur un bundle corrigé en direct, Sentry résout les cadres contre la carte de source pour cette mise à jour en direct au lieu du bundle de magasin plus ancien.

Cela compte avec tout workflow de mise à jour OTA. Si vous souhaitez une bonne introduction aux pièces en mouvement derrière ce modèle de livraison, cette explication de how live updates work in Capacitor apps est une référence solide.

Voici le type de vue opérationnel que les équipes visent lorsqu'elles combinent les métadonnées de mise à jour avec la suivi des versions :

Les principales erreurs à éviter sont de réutiliser une chaîne de mise à jour statique pour chaque mise à jour de l'application. Si plusieurs bundles partagent la même version de Sentry, le débogage devient à nouveau une supposition.

Si votre équipe livre des correctifs en dehors des cycles de revue de l'App Store, 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.