Sentry React Native : Guide d'intégration 2026

Vous avez un application React Native fonctionnant localement, la QA a validé et la production est proche. Puis 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'un 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 L'installation de base est la partie facile. . Les parties douloureuses viennent ensuite : l'intégration native, la symbolisation, les cartes de sources, la dé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 paramétrage doit survivre aux CI, aux builds de l'App Store, aux sorties Android et aux bundles JavaScript qui ne viennent pas toujours du code original.

Table des matières

• Démarrage avec Sentry SDK
  • Ce dont vous avez besoin avant l'installation
  • Exécution du sorcier et examen du résultat
• Configuration des projets iOS et Android natifs
  • Ce qui a changé sur iOS
  • Ce qui a changé sur Android
  • Vérifications de paramétrage 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 les données de performance et les événements personnalisés
  • Suivre un é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
  • Ce que vérifier dans l'interface utilisateur de Sentry
  • Dépannage React Native Sentry commun
• Intégrer avec les workflows d'actualisation en direct comme Capgo
  • Correspondre les identifiants de version à des paquets en direct

Prise en main avec Sentry SDK

La méthode la plus rapide pour intégrer Sentry React Native dans une nouvelle application est toujours le guide d'installation. Il gère la plupart des paramètres répétitifs 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'à la première panne en production.

Ce dont vous avez besoin avant l'installation

Vous avez besoin d'un environnement de développement React Native 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 marketing autour des compromis de plateforme, de la gestion du personnel et des attentes de maintenance. Il est utile de le lire avant de vous engager dans votre processus de monitoring et de mise en production autour d'un codebase 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 du projetSélectionnez 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 ce que vous savez que vous utiliserez, mais ne permettez pas tout sans examen si votre équipe ne passe pas en revue les données résultantes.

Exécution du guide et examen du résultat

Après la fin du guide, inspectez les modifications au lieu de les faire confiance sans examen. Vous devriez voir un paquet Sentry dans package.json, des modifications natives sous ios , et un bloc d'initialisation dans votre fichier d'entrée d'application. androidUn exemple d'initialisation ressemble à ceci :

Le

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

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

DSN indique au __CAPGO_KEEP_0__ où envoyer les événements. Traitez-le comme une configuration, et non comme un coffre-fort secret qui doit toujours rester invisible. Cela n'est pas la même chose qu'un jeton d'authentification. Cependant, gardez votre configuration d'environnement propre et cohérent pour que votre application pointe vers le bon projet Sentry dans chaque environnement. 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.

Un modèle pratique consiste à charger la DSN à partir de la configuration spécifique à l'environnement et à initialiser Sentry avant que le reste de l'arbre d'application ne monte. Si vous travaillez également sur la mise en forme de démarrage, ce guide sur la configuration de l'écran de démarrage de React Native est utile car l'ordre de démarrage de l'application souvent se chevauche 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 fonctionne, les couches natives et de version deviennent beaucoup plus faciles à raisonner.

Configuration des Projets iOS et Android natifs

À cette étape, de nombreux équipes de React Native ont une fausse impression de complétion. Le JavaScript __CAPGO_KEEP_0__ 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.

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.

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

Dans Xcode, vérifiez ces endroits :

Démarrage de l'application du délégué __CAPGO_KEEP_0__

• code. L'application nécessite une initialisation native de Sentry tôt dans la lancement.
• Phases de construction. Cherchez tout script de téléchargement de Sentry lié aux symboles de débogage ou à la gestion des 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 builds d'archive.

Si votre application utilise AppDelegate.mm, l'initialisation se situe souvent près de l'initialisation du pont de liaison React Native. Le contenu du fichier peut varier en fonction de la version de React Native, du modèle et de l'utilisation de l'architecture nouvelle, n'importez donc pas des snippets de fichiers aléatoires à moins qu'ils correspondent à la forme de votre projet.

Ce qui compte 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.

Si les défaillances d'iOS apparaissent dans Sentry avec des cadres natifs non lus, le problème est généralement "Sentry n'est pas cassé." C'est l'upload de symboles ou la correspondance de la version de sortie.

Ce qui a changé sur Android

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

Choses à vérifier :

1. Le plugin Sentry Gradle est appliqué ainsi que les artefacts de version peuvent être traités pendant le temps de build.
2. Le traitement des variantes est normal s'il utilise des saveurs de produit ou plusieurs types de build.
3. Les sorties de ProGuard ou R8 sont prises en compte s'il s'agit de builds de version qui réduisent ou masquent code.

Une erreur commune Android est d'assumer 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, cette analyse des types de build mobile 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

N'arrêtez pas à « le sorcier a modifié des fichiers ». Vérifiez le comportement directement.

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 du nom de package et de 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 celle qui est sans intérêt. Les appels de démarrage natifs sont en place, les scripts de construction s'exécutent chaque fois et le nom de la version est déterministe sur iOS, Android et les bundles JavaScript.

Automatiser les sorties et les cartes de sources

S'il y a un 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. Puis la première question sérieuse de production arrive et la pile de traces est minimisée, la version manque ou l'upload de la carte de sources appartenait à un bundle différent.

Les uploads de cartes de sources manuels semblent acceptables lorsqu'on expédie rarement. Dans la pratique, ils échouent car les humains sont mauvais dans la tenue de livres de versions répétitives.

Pourquoi les uploads manuels échouent dans la pratique

Les modes d'échec 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 code binaire ou le paquet 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 la téléchargement des 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 de Sentry et des cartes de source pour React Native.

Un processus de versionnement qui tient vraiment la route : 

• Les IDs de version sont générés une seule fois et réutilisés partout.
• Les étapes de construction, de mise en boîte 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 a utilisée lors de l'upload.

Ce dernier point est plus important que ce à quoi on s'attend souvent. 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 des flux de build et de version avec GitHub Actions s'inscrit bien dans le même modèle opérationnel.

A 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 bundle 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 scripting ingénieux. Choisissez une convention de nommage, injectez-la dans l'application lors de la phase de construction, et n'autorisez jamais les téléchargements ad hoc locaux à concurrencer CI.

Pour React Native, je préfère stocker la chaîne de mise en production dans une localisation de configuration générée par la phase de 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 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 se décider à abandonner.

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

Suivre un é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 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 tard.
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 l'application webview ou hybride, cet article sur la surveillance de performances dans les projets Capacitor vaut la peine de l'inspecter car l'esprit opérationnel est similaire même si le pilon diffère.

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 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 intention :

• Contexte de l'utilisateur avec Sentry.setUser() afin que le support puisse corrélater les rapports à un compte affecté sans passer par des suppositions.
• Miettes pour les actions comme appuyer sur le bouton soumettre, ouvrir un modal ou démarrer une synchronisation.
• Étiquettes personnalisées pour des dimensions comme le type de plan, l'état d'une bannière de fonctionnalité ou API région.
• Exceptions capturées avec un contexte supplémentaire lorsque vous riez et rejetez ou faites surface à des échecs 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 passe mal, elle se passe généralement mal en étant trop bruyante. Ne capturez pas chaque appui sur le bouton dans l'application pour toujours. Capturer les limites, les transitions d'état et les opérations qui comptent lors de la déboguage. Assez de contexte pour expliquer l'événement. Pas assez 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 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 d'inspecter comment ils arrivent dans Sentry.

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

Pour une erreur JavaScript, ajoutez un bouton temporaire sur 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'assistance exactes disponibles peuvent varier en fonction de la version et de la configuration de SDK, 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 mon propre chemin de crash.

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

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

Vérifiez ces champs :

• Plateforme et mécanisme Cela 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.
• Frames de pile Les emplacements de source lisibles devraient apparaître pour les cartes JavaScript correctement chargées.
• Breadcrumbs 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 unique.

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

Dépannage React Native Sentry Commun

Une dernière 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 environnement 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 mise en production. Le fichier binaire dans l'application 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 la mise en production de Sentry suive le paquet JavaScript en direct et non seulement le fichier binaire natifCorrespondance des identifiants de mise en production aux paquets en direct

Pour les workflows d'actualisation en direct, traitez

et release comme des identifiants de temps d'exécution 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 dist Un modèle pratique ressemble à ceci :

__CAPGO_KEEP_0__

• Utilisez la version de l'application native en tant que partie du nom de la version de base.
• Appendez la version de mise à jour en direct ou l'identifiant du paquet.
• 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 sources 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,
});

Cela permet, lorsque l'utilisateur rencontre une erreur sur un bundle hotfixé, que Sentry résolve les cadres contre la carte de sources pour ce hotfix au lieu du bundle de magasin plus ancien.

Cela compte avec tout workflow de mise à jour OTA. how live updates work in Capacitor apps comment les mises à jour en direct fonctionnent dans les applications __CAPGO_KEEP_0__

est une référence solide.

The main mistake to avoid is reusing one static release string for every post-store update. If multiple bundles share the same Sentry release, debugging turns into guesswork again.

Si votre équipe livre 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 des mises à jour en direct, de cibler les canaux, de contrôler les déploiements et de se rétablir rapidement de mauvaises mises en production. Associez cela à une nomination disciplinée des versions Sentry et à des téléchargements de cartes de sources, et vous obtenez un flux de travail où les erreurs pointent toujours vers les utilisateurs code exacts qui exécutent.