Guide d'intégration de Sentry React Native 2026 : de l'installation à la mise en œuvre

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

Sans Sentry, la réponse est généralement mauvaise. Vous obtenez un ticket de support, un écran de capture vague, peut-être un journal de console d'un build de développeur 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 l'installation de base est la partie facile. Les parties douloureuses viennent ensuite : intégration native, symbolisation, cartes de sources, nommage de version, et garder tout cela aligné quand 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 versions Android, et aux bundles JavaScript qui ne viennent pas toujours du binôme original.

Table des matières

• Prise en main avec Sentry SDK
  • Ce que vous devez avoir avant d'installer
  • Exécuter le sorcier et examiner le résultat
• Configurer les projets iOS et Android natifs
  • Qu'est-ce qui a changé sur iOS
  • Qu'est-ce qui a changé sur Android
  • Vérifications de mise en place natives qui économisent du temps plus tard
• Automatiser les lancements et les cartes de sources
  • Pourquoi les téléchargements manuels échouent en pratique
  • Un processus de lancement qui tient vraiment
  • Un modèle de script CI pratique
• Capturer des données de performance et des événements personnalisés
  • Déterminer 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
  • What to check in the Sentry interface
  • Résolution courante des problèmes de Sentry React Native
• Intégration avec les flux de mise à jour en direct comme Capgo
  • Correspondance des identifiants de version avec les lots en direct

Prise en main de la Sentry SDK

La façon la plus rapide pour intégrer 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 ligne de travail fonctionnelle. Cela compte, car la mise en place manuelle de la première installation conduit généralement à 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 Native normal d'abord. 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 fournit un contexte non marketing autour des compromis de plateforme, de personnel et d'attentes de maintenance. Il est utile de le lire avant de vous engager dans votre processus de suivi et de mise en production autour d'un code partagé.

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

npx @sentry/wizard@latest -i reactNative

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

• Sélection de projet. Sélectionnez le projet Sentry réel que vous prévoyez utiliser en production, et non un sandbox temporaire que vous oublierez de mettre à jour plus tard.
• Changements natifs. Dites oui. La capture d'erreurs uniquement en JavaScript n'est pas suffisante pour les applications mobiles.
• Fonctionnalités optionnelles. Activez ce que vous savez que vous utiliserez, mais n'activez pas tout de manière aveugle dès le premier jour si votre équipe ne passera pas en revue les données résultantes.

Exécution du sorcier et examen du résultat

Après que le sorcier ait terminé, inspectez les modifications au lieu de les faire confiance sans examen. Vous devriez voir un package Sentry dans package.json, des changements natifs sous ios et android, et un bloc d'initialisation dans votre fichier d'entrée de l'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, pas comme un coffre-fort secret qui doit toujours rester invisible. Cela ne s'agit pas du même chose qu'un jeton d'authentification. Cependant, gardez votre configuration d'environnement propre et cohérente afin que votre application pointe vers le bon projet Sentry dans chaque environnement.

Un modèle pratique est de charger le DSN à partir de la configuration spécifique à l'environnement et d'initialiser Sentry avant que le reste de votre tree d'application ne monte. Si vous travaillez également sur la mise en forme de démarrage, ce guide sur la mise en place de l'écran de démarrage de React Native est utile car l'ordre de démarrage de l'application __CAPGO_KEEP_0__ souvent intersecte avec où les équipes placeraient l'initialisation de Sentry. is useful because startup code order often intersects with where teams place Sentry initialization.

initialisez Sentry aussi tôt que possible dans le démarrage de l'application. Si vous attendez jusqu'à après la navigation, l'hydratation d'authentification ou la configuration à distance, vous manquerez les erreurs de démarrage. À cette étape, 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.

Configuration des Projets iOS et Android natifs

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

DSN tells the SDK where to send events. Treat it as configuration, not as a secret vault item that must never be visible. It isn’t the same as an auth token. Still, keep your environment setup clean and consistent so your app points to the right Sentry project in each environment. A practical pattern is to load the DSN from environment-specific config and initialize Sentry before the rest of your app tree mounts. If you’re also working through startup polish, this guide to React Native splash screen setup is useful because startup SDK order often intersects with where teams place Sentry initialization. Practical rule: initialize Sentry as early as possible in app startup. If you wait until after navigation, auth hydration, or remote config, you’ll miss startup failures. At this stage, don’t chase perfection. The immediate goal is simple: launch the app, trigger a JavaScript exception later in the article, and confirm events reach Sentry. Once that’s working, the native and release layers become much easier to reason about. Configuring Native iOS and Android Projects 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.

Qu'est-ce qui a changé sur iOS

Ouvrez le projet iOS et passez en revue ce que le sorcier a changé. Dans une application React Native nue, cela signifie généralement des mises à jour autour des phases de démarrage et de construction de l'application. Vous cherchez les appels de fonctions d'initialisation de Sentry et les étapes d'envoi liées à votre processus de construction.

Dans Xcode, vérifiez ces endroits :

• Le délégué d'application de démarrage code. L'application a besoin d'une initialisation native de Sentry tôt dans le lancement.
• Phases de construction. Cherchez tout script d'envoi de Sentry lié à la gestion de symboles de débogage ou de cartes de sources.
• Paramètres de construction et comportement d'archive. Les fichiers de symboles doivent être générés et disponibles pendant les constructions d'archive.

Si votre application utilise AppDelegate.mm, l'initialisation se situe souvent près de l'amorçage de la passerelle React Native. Le contenu du fichier peut varier en fonction de la version de React Native, du modèle et de l'utilisation de la nouvelle architecture, donc ne copiez pas de snippets de répos aléatoires à moins qu'ils correspondent à la forme de votre projet.

Ce qui compte, c'est l'intention : les défaillances natives d'iOS nécessitent des données de symboles, et l'application doit démarrer Sentry avant que la défaillance puisse être observée de manière fiable.

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

What changed on Android

Android ajoute généralement des changements dans les fichiers Gradle et parfois des configurations au niveau du manifeste. Vérifiez android/build.gradle, android/app/build.gradle, et tout plugin ou tâche lié à Sentry.

Détails à vérifier :

1. Le plugin Gradle de Sentry est appliqué pour 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 de ProGuard ou R8 sont prises en compte si vos builds de version minimisent ou obfusquent code.

Une erreur courante sur Android est de supposer qu'une 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 minimisation 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émantèlement de types de build mobile est une référence utile pour maintenir le comportement de suivi aligné sur chaque variante de build.

Vérifie les paramètres de setup natif qui économisent du temps plus tard

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

Utilisez ce tableau de vérification :

• Archiver un build iOS localement et confirmez que le build ne faille pas pendant le traitement des symboles.
• Créer un build de release Android et inspectez les journaux CI pour les tâches liées à Sentry.
• Vérifiez la correspondance entre le nom de package et l'identifiant de l'application dans Sentry si vous gérez plusieurs applications sous une même organisation. Confirmez les conventions de nommage des releases maintenant
• __CAPGO_KEEP_0__avant le démarrage de CI, les artefacts sont chargés sous des noms incohérents.

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

La meilleure mise en place est ennuyeuse. Les appels de démarrage natifs sont en place, les scripts de build s'exécutent chaque fois et le nommage de la version est déterministe sur iOS, Android et les bundles JavaScript.

Automatiser les sorties et les cartes de sources

Si l'un des endroits où les configurations de Sentry React Native se défont, c'est ici. Les équipes installent le SDK, voient les événements, et retardent l'automatisation de la mise en production. Puis la première véritable erreur de production arrive et la trace de pile est minimisée, la mise en production manque, ou le téléchargement de la carte source appartient à un autre bundle.

Les téléchargements de cartes source manuels semblent acceptables lorsque vous expédiez rarement. Dans la pratique, ils échouent car les humains sont mauvais pour le tenir à jour du livre de relais de mise en production répétitif.

Pourquoi les téléchargements manuels échouent en pratique

Les modes de défaillance 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 autre commit que le bundle binaire ou OTA que les utilisateurs exécutent.
• Le nom de la mise en production change légèrement entre les étapes iOS, Android et CI.
• Une reconstruction se produit après le téléchargement de la carte et invalide ce que Sentry devrait correspondre à.

C'est pourquoi je ne recommande pas une approche « documenter les étapes dans Notion ». Cela fonctionne jusqu'à ce qu'une mise à jour urgente soit publiée sous pression.

Un processus de mise à jour qui tient vraiment

Un setup fiable a quelques propriétés :

• Les identifiants de mise à jour sont générés une seule fois et réutilisés partout.
• Les étapes de construction, de bundling et d'upload se produisent dans le même pipeline.
• Les cartes de sources sont chargé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 mise à jour que CI a utilisée lors de l'upload.

Ce dernier point compte plus que l'on ne le pense généralement. Vous n'avez pas seulement besoin de cartes de sources dans Sentry. Vous avez besoin de les cartes de déploiement 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 sur flux de construction et de publication automatiques avec GitHub Actions s'inscrit bien dans le même modèle opérationnel.

Un modèle de script CI pratique

Utilisez un script comme celui-ci dans CI et alimentez les valeurs de votre pipeline d'environnement :

#!/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 déploiement l'emporte sur la scripting ingénieux. Choisissez une convention de nommage, injectez-la dans l'application en temps de construction, et n'autorisez jamais les uploads ad hoc locaux à concurrencer CI.

Pour React Native, j'ai préféré stocker la chaîne de version dans un emplacement de configuration généré par la construction 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 le code que vous avez expédié, et non vers le code que vous pensez avoir expédié.

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

Crashs vous disent ce qui s'est cassé. La détection de performances vous dit ce que les utilisateurs ont ressenti avant de lâcher prise.

Un rapport commun ressemble à ceci : « Le tableau de bord est lent. » Cela ne suffit pas pour déboguer. Lent où ? Pendant la navigation ? Lors de la récupération des données ? Alors que vous affichez un graphique lourd ? Sentry devient utile ici lorsque vous arrêtez de le traiter comme un boîtier d'erreurs et 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. Puis reproduisez le grief sur un appareil physique, pas seulement 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 de discuter sur des sentiments.

Pour les équipes qui réfléchissent de manière large sur les modèles de surveillance de la vue web ou d'applications hybrides, ce billet sur la surveillance de la performance dans les projets Capacitor vaut la peine de l'inspecter car l'esprit opérationnel est similaire même si le stack diffère.

Ajouter un contexte utile aux erreurs

Les données de performance deviennent plus utiles lorsque les événements transportent un contexte commercial. Pas de métadonnées vanité. Juste assez pour répondre à qui a été affecté, sur quelle page ils étaient et ce qui s'est passé juste avant l'erreur.

Utilisez ces outils avec intentionnalité :

• Contexte de l'utilisateur avec Sentry.setUser() pour que le support puisse corriger les rapports à un compte affecté sans passer par des suppositions.
• Breadcrumbs pour les actions comme appuyer sur le bouton soumettre, ouvrir un modale ou lancer un synchronisation.
• Balises personnalisées pour des dimensions comme le type de plan, l'état de la bannière de fonctionnalité ou API région.
• Exceptions capturées avec un contexte supplémentaire lorsque vous attrapez et rejetez ou faites surface de pannes contrôlées.

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 boulons est souvent la différence entre « l'utilisateur dit que l'application s'est bloquée » et « l'application a échoué après avoir ouvert le tableau de bord, démarré la synchronisation et réessayé une demande périmée ».

Lorsque l'instrumentation personnalisée se trompe, elle se trompe généralement en étant trop bruyante. N'attrapez pas chaque pression de bouton dans l'application pour toujours. Attrapez les limites, les transitions d'état et les opérations qui comptent lors de la débogage. Un contexte suffisant pour expliquer l'événement. Pas suffisamment pour l'étouffer.

Vérification et Dépannage de votre Intégration

Vous devriez vérifier Sentry avant de livrer, après les modifications du pipeline de construction et après SDK mises à jour. « Cela fonctionnait des mois auparavant » n'est pas un test significatif.

La manière la plus propre est de déclencher des pannes contrôlées pour les deux chemins JavaScript et natifs, puis inspectez comment ils arrivent dans Sentry.

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

For un erreur JavaScript, ajoutez un bouton temporaire sur une page non productive :

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

Pour une exception capturée qui ne fera pas crash 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 des builds de développement ou de QA contrôlés. Les méthodes d'aide exactes disponibles peuvent varier en fonction de la version et de la configuration de SDK et de la plateforme, donc je préfère utiliser l'utilitaire de test de crash natif documenté de SDK lorsqu'il est présent plutôt que d'inventer votre propre chemin de crash.

Quels éléments vérifier dans l'interface de l'outil Sentry :

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

Vérifiez ces champs :

• Plateforme et mécanismeCela aide à distinguer les exceptions JavaScript des crashs natifs.
• Release et distS'il s'agit de champs vides ou incorrects, les cartes de source et la symbolication seront décalés.
• Stack framesLes emplacements de source lisibles devraient apparaître pour les cartes de JavaScript uploadées correctement.
• Miettes et étiquettes. Confirmez que votre contexte personnalisé est arrivé.
• Environnement. Assurez-vous que les événements de développement et de production ne soient 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'artifact de build.

Problèmes de dépannage React Native Sentry courants

Une habitude qui rapporte est de garder une petite « liste de vérification de test de fumée de monitoring » dans votre processus de mise en production. Déclenchez un événement JS en phase de test, confirmez les valeurs de mise en production 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 version. Le fichier binaire dans la boutique peut rester le même tandis que le paquet JavaScript change sous-jacent. Si Sentry pense toujours en termes de version d'application originale, les traces de pile deviennent rapidement trompeuses

La solution est de faire en sorte que l'identité de version de Sentry suive le paquet de mise en direct et non seulement le fichier binaire natifLes identifiants de version correspondants aux paquets de mise en direct

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

Pour les flux de mise à jour en temps réel, traitez release et dist comme des identifiants liés à l'exécution liés au package JavaScript délivré. La version de l'application native compte toujours, mais ce n'est pas suffisant une fois que les bundles peuvent changer indépendamment.

Un modèle pratique ressemble à ceci:

• Utilisez la version de l'application native comme partie du nom de version de base.
• Ajoutez la version de mise à jour en temps réel ou l'identifiant du package.
• Utilisez dist pour la différenciation spécifique au canal ou à la construction lorsque cela convient à votre modèle.
• Chargez les cartes de source pour chaque bundle en temps réel sous cet identifiant de version exact.

Par exemple, si votre application charge les métadonnées de mise à jour au démarrage, initialisez Sentry avec des valeurs dérivées de la bundle active actuellement, et non seulement 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 hotfixé, Sentry résout les cadres contre la carte de source pour ce hotfix au lieu de la plus ancienne bundle de magasin.

Cela compte avec tout workflow de mise à jour OTA. Si vous voulez une bonne introduction aux pièces en mouvement derrière ce modèle de livraison, cette explication de How les mises à jour en temps réel fonctionnent dans les applications Capacitor est une référence solide.

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

L'erreur principale à éviter est de réutiliser une chaîne de version statique pour chaque mise à jour post- magasin. Si plusieurs ensembles partagent la même version Sentry, le débogage se transforme en un jeu d'essais et d'erreurs.

Si votre équipe expédie des correctifs en dehors des cycles de revue des magasins d'applications, Capgo est digne d'être évalué. Il donne aux équipes Capacitor une façon structurée de livrer les mises à jour en temps réel, de cibler les canaux, de contrôler les déploiements et de se rétablir rapidement des versions défectueuses. Associez cela à une discipline de nommage des versions Sentry et de téléchargement de cartes de sources, et vous obtenez un flux de travail où les erreurs pointent toujours vers les code exacts que les utilisateurs exécutent.