Sentry React Native : Guide d'intégration 2026

Vous avez un application React Native qui fonctionne localement, la QA a donné son accord 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 de capture 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 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 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

• Getting Started with the Sentry SDK
  • Ce dont vous avez besoin avant d'installer
  • 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
  • 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 des données de performance et des événements personnalisés
  • Suivre un écran lent plutôt que 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 commun de Sentry React Native
• Intégrer avec des flux de mise à jour en direct comme Capgo
  • Correspondre les identifiants de version à des lots en direct

Commencer avec SDK

La méthode la plus rapide pour intégrer Sentry React Native dans une nouvelle application est toujours l'assistant 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 entraîne 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 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 fournit un contexte utile non marketing 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 l'assistant d'installation depuis la racine du projet :

npx @sentry/wizard@latest -i reactNative

L'assistant demande quelques choses que les développeurs cliquent souvent trop rapidement :

• Sélection du projetChoisissez 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. Dis l'essentiel. La capture d'erreurs uniquement en JavaScript ne suffit pas pour les applications mobiles.
• Fonctionnalités optionnelles. Activez uniquement ce que vous savez que vous utiliserez, mais ne vous laissez pas aveuglément everything le jour de votre équipe ne révisera pas 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, modifications natives sous ios et android, et un 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, pas comme un coffre-fort secret qui doit toujours rester invisible. Ce 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.

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 démarrage de React Native est utile car l'ordre de démarrage de l'application intersecte souvent avec l'emplacement où les équipes placeraient l'initialisation de Sentry. La mise en place de l'écran de démarrage 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 nombreuses é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 gestion 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.

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__

• code. L'application nécessite une initialisation native de Sentry tôt dans le lancement.
• Phases de construction. Cherchez tout script d'upload 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 builds d'archive.

Si votre application utilise AppDelegate.mm, l'initialisation se situe 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, donc n'importez pas de snippets de répertoires aléatoires à moins qu'ils correspondent à la forme de votre projet.

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

Si les plantages 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. Vérifiez android/build.gradle, android/app/build.gradleet toute configuration ou tâche liée à Sentry.

Les éléments à vérifier :

1. Le plugin Sentry Gradle 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 ProGuard ou R8 sont prises en compte si vos builds de version réduisent ou masquent 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 la 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étail de les 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

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

Utilisez cette liste de vérification :

• Archivez une build iOS localement et confirmez que la build ne faille pas pendant le traitement des symboles.
• Créez une 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 bundle dans Sentry si vous gérez plusieurs applications sous une même organisation.
• Confirmez 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 sans intérêt. 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 tombent en pièces, c'est ici. Les équipes installent le SDK, voient des événements, et reportent 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 manuels de cartes de sources semblent acceptables lorsque vous expédiez rarement. En pratique, ils échouent car les humains sont mauvais pour le suivi répétitif des livraisons.

Pourquoi les uploads manuels échouent en pratique

Les modes d'échec sont prévisibles :

• Quelqu'un oublie de télécharger les cartes après une mise à jour nocturne.
• Les fichiers téléchargés appartiennent à un commit différent que le paquet binaire ou 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 : 

• Les identifiants de version sont générés une fois et réutilisés partout.
• Les étapes de construction, de paquetage et d'upload se produisent dans le même pipeline.
• Les cartes de source sont chargées à partir de CIet 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. Cette dernière 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 de la construction et des flux de version avec __CAPGO_KEEP_0__ Actions.

s'inscrit bien dans le même modèl’opérationnel. automatic build and release workflows with GitHub Actions et non à partir d'un ordinateur portable de développeur.

Au-delà des scripts CI pratiques

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 compilation, 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 compilation 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 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é. Les traçages de performance vous disent ce que les utilisateurs ont ressenti avant de renoncer.

Un rapport commun ressemble à ceci : « Le tableau de bord est lent. » Cela ne suffit pas à 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 le traiter 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 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 l'application webview ou hybride, cet article sur la surveillance de performances dans les projets __CAPGO_KEEP_0__ est worth de l'inspecter car l'esprit opérationnel est similaire même si le pilier diffère. 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 est worth de l'inspecter car l'esprit opérationnel est similaire même si le pilier diffère. 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 __CAPGO_KEEP_0__ est worth de l'inspecter car l'esprit opérationnel est similaire même si le pilier 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 vaniteuses. Juste assez pour répondre à qui a été affecté, sur quelle page ils se trouvaient, et ce qui s'est passé juste avant la panne.

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.
• Breadcrumbs pour les actions comme appuyer sur le bouton soumettre, ouvrir un modal, ou démarrer une 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 riez 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 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 dégrade, elle se dégrade généralement en étant trop bruyante. Ne capturez pas chaque pression de bouton dans l'application à tout jamais. 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 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 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 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'assistance exactes disponibles peuvent varier en fonction de la version de SDK et de la mise en câblage 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 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écanismeCela aide à distinguer les exceptions JS des crashes natifs.
• Version et distSi elles sont vides ou incorrectes, les cartes de sources et la symbolication dériveront.
• Fenêtres de pileLes emplacements de source lisibles devraient apparaître pour les cartes JavaScript correctement chargées.
• Miettes et étiquettesConfirmez que votre contexte personnalisé est arrivé.
• EnvironnementAssurez-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, 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 étape 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 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 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 d'application native en tant que partie du nom de version de base.
• Appendez la version d'actualisation en direct ou l'identifiant de package.
• Utilisez dist pour la différenciation par canal ou spécifique à 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 d'actualisation au démarrage, initialisez Sentry avec des valeurs dérivées de la version active de bundle actuelle, 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 hotfixé, Sentry résout les frames contre la carte de sources pour ce hotfix au lieu de la version de stockage plus ancienne.

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

Voici le type de vue opérationnelle que les équipes visent lorsqu'elles combinent les métadonnées d'actualisation avec la suivi des versions :

Évitez surtout de réutiliser une chaîne de mise en production statique pour chaque mise à jour de l'application. Si plusieurs bundles partagent la même version de Sentry, le débogage se transforme à nouveau en jeu d'essais.

Si votre équipe livre des correctifs en dehors des cycles de revue des magasins d'applications, 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.