Guide d'intégration de Sentry React Native 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 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 console log 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 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 direct.

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 releases Android, et aux bundles JavaScript qui ne viennent pas toujours du binôme original.

Table des Matières

• Getting Started with the Sentry SDK
  • Commencer avec Sentry __CAPGO_KEEP_0__
  • Ce dont vous avez besoin avant l'installation
• Exécuter le wizard et examiner le résultat
  • Configurer les projets iOS et Android natifs
  • Ce qui a changé sur Android
  • Configuration de native qui économise du temps plus tard
• Automatiser les Lancements et les Cartes de Source
  • Why manual uploads fail in practice
  • Un processus de mise à jour qui tient vraiment
  • Un modèle de script CI pratique
• Capturing Performance Data and Custom Events
  • Déterminer une écran lent au lieu de deviner
  • Ajouter un contexte utile aux erreurs
• Vérifier et résoudre les problèmes de 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
  • Résolution de problèmes React Native Sentry courants
• Intégration avec les workflows comme Live Update et Capgo
  • Matching release identifiers to live bundles

Prise en main de la Sentry 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 ligne 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 fournit un contexte non commercial utile autour des compromis de plateforme, des effectifs et des attentes de maintenance. Il est recommandé de le lire avant de vous engager dans le suivi et le processus de mise à jour autour d'un code partagé.

Installez la 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 trop rapidement :

• Projets à sélectionnerSélectionnez le projet Sentry réel que vous comptez utiliser en production, et non un sandbox temporaire que vous oublierez de mettre à jour.
• Changements natifs. Dit oui. La capture d'erreurs uniquement en JavaScript ne suffit pas pour les applications mobiles.
• Fonctionnalités optionnellesActivez uniquement les fonctionnalités que vous savez utiliser, mais n'activez pas tout d'un coup sans que votre équipe n'ait pu examiner 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.jsonchangements natifs 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 élément de coffre-fort qui doit toujours rester invisible. Il ne s'agit pas du 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 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 Configuration de l'écran d'accueil React Native est utile car l'ordre de démarrage du projet code se croise souvent avec l'emplacement où les équipes initient Sentry.

Règle pratique: Initialisez Sentry le plus tôt possible au démarrage de l'application. Si vous attendez jusqu'à la navigation, l'hydratation d'authentification ou la configuration distante, vous manquerez les erreurs de démarrage.

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.

Configurer les Projets iOS et Android Natives

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.

Quels changements sur iOS

Open the iOS project and review what the wizard changed. In a bare React Native app, that usually means updates around app startup and build phases. You’re looking for Sentry initialization hooks and upload steps tied to your build process.

Vérifiez ces endroits dans Xcode :

• Lancement de l'application code. L'application nécessite 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 builds d'archive.

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

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

Si les crashes iOS apparaissent dans Sentry avec des cadres natifs non lisible, le problème est généralement lié à l'upload de symboles ou à la correspondance de la version de release.

Ce qui a changé sur Android

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

Les choses à vérifier :

1. Le plugin Gradle Sentry est appliqué Les artefacts de la version peuvent ê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 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émantèlement des types de build mobile est une référence utile pour maintenir le comportement de surveillance aligné sur chaque variante de build.

Configuration de native qui économise du temps plus tard

N'arrêtez pas à « les fichiers modifiés par le sorcier ». Vérifiez le comportement directement.

Utilisez ce tableau de vérification :

• Archiver une build iOS localement et confirmer que la build ne faille pas pendant le traitement des symboles.
• Créer une release Android build 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 en Sentry si vous gérez plusieurs applications sous une même organisation.
• Confirm release naming conventions nowavant 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 Lancements et les Cartes de Source

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

Les téléchargements de cartes source manuels sont acceptables lorsqu'on livre rarement. En pratique, ils échouent car les humains sont mauvais en tenue de livraison répétitive.

Why manual uploads fail in practice

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 les utilisateurs exécutent.
• Le nom de la version change légèrement entre les étapes iOS, Android et CI.
• Une reprise se produit après l'upload de la carte. et invalide ce que Sentry devrait correspondre.

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 ses promesses

Un setup fiable a quelques propriétés :

• Les IDs de version sont générés une fois et réutilisés partout.
• Étapes de construction, de paquetage et d'upload se déroulent dans le même pipeline..
• Les cartes de source sont chargées à partir de CIpas d'un ordinateur de développeur.
• L'application initialise Sentry avec la même chaîne de version de sortie. ce CI utilisé lors de l'upload.

des cartes de sources correctes attachées à l'identifiant de version exactement émis par l'application au moment de l'exécution. les cartes de source correctes attachées à l'identifiant de version exactement émis par l'application en temps de exécution.

Si votre équipe a déjà standardisé l'automatisation mobile, ce guide sur flux de build et de publication automatiques avec des Actions GitHub Un modèle de script CI pratique

Un modèle de script CI pratique

Use a script like this in CI and feed values from your pipeline environment:

#!/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"

You’ll need to adapt the bundle command for Android, and many teams split platform-specific jobs instead of forcing one script to do both. That’s fine. What matters is consistency.

Discipline de versionning l'emporte sur la scripting raffiné. Pour React Native, je préfère stocker la chaîne de mise en production dans une emplacement de configuration généré par la construction et la lire pendant

Pour React Native, j'ai préféré stocker la chaîne de version dans un emplacement de configuration généré par la build et la lire ensuite. Sentry.init():

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

The payoff is simple. When an event arrives, Sentry can map the minified frame back to the code you shipped, not the code you think you shipped.

Capturing Performance Data and Custom Events

Les crashes vous disent ce qui a cassé. Les traces de performances vous disent ce que les utilisateurs ont ressenti avant de renoncer.

Avec un rapport commun, cela 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 ? Lors de la mise en page d'un graphique lourd ? Sentry devient utile ici lorsque vous arrêtez de le traiter comme un boîte aux lettres d'erreurs et commencez à instrumenter le comportement de l'application.

Suivre la traçabilité d'une écran lent plutôt que 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 pour que les transitions d'écran produisent des données de traçage. Reproduisez ensuite la plainte 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 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, réexpédiez, et comparez la nouvelle forme de trace.

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

For teams thinking broadly about webview or hybrid app monitoring patterns, this write-up on surveillance de performance dans les projets Capacitor est digne d'être lu car l'esprit opérationnel est similaire même si le pilier diffère.

La mise en contexte utile des erreurs

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

Utilisez ces outils avec intentionnalité :

• Le contexte de l'utilisateur avec Sentry.setUser() afin que le support puisse corriger les rapports à un compte affecté sans se perdre dans des suppositions.
• Les miettes pour les actions comme appuyer sur soumettre, ouvrir un modal, ou démarrer une synchronisation.
• Custom tags pour des dimensions comme type de plan, état de la bannière de fonctionnalité ou région API.
• 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 l'ouverture du tableau de bord, le démarrage de la synchronisation et la réessai d'une demande périmée ».

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 à jamais. Capturez 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

Vérifiez Sentry avant de livrer, après les modifications du pipeline de build 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 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écurisée

Pour une erreur JavaScript, ajoutez un bouton temporaire dans un é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 planter 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 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 votre 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 JavaScript des crashes natifs.
• Mise en production 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 balises. Confirmez que votre contexte personnalisé est arrivé.
• EnvironnementAssurez-vous que les événements de développement et de production ne soient 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’artifact de build.

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

Une bonne habitude à adopter est de conserver une petite « liste de vérification de test 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 de Live Update comme les Capgo

Les mises à jour en temps réel modifient 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 liveet non seulement le binaire natif

Correspondance des identifiants de publication aux paquets live

Pour les workflows de live update , traitez-les release et dist comme identifiants de runtime liés au package JavaScript 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 ou l'identifiant du package live update.
• Utilisez dist pour la différenciation du canal ou de la build lorsque cela correspond à votre modèle.
• Téléchargez les cartes de source pour chaque bundle live 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 l'ensemble actif de bundles, et non seulement à partir de la configuration de build 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é, à Sentry de résoudre les frames contre la carte de source pour ce hotfix au lieu de l'ancien bundle de magasin.

Cela compte avec tout workflow OTA. Si vous souhaitez une introduction complète sur les 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 d'affichage opérationnel que les équipes visent lorsqu'elles combinent les métadonnées d'actualisation avec la suivi des versions :

L'erreur majeure à éviter est de réutiliser une chaîne de version statique pour chaque mise à jour post-stockage. Si plusieurs lots partagent la même version Sentry, le débogage se transforme à nouveau en un jeu d'avis.

If your team ships fixes outside app store review cycles, Capgo est une solution à évaluer. Elle donne aux équipes Capacitor une méthode structurée pour livrer des mises à jour en direct, cibler les canaux, contrôler les déploiements et se rétablir rapidement en cas de mauvaises versions. Associez cela à une nomination disciplinée des versions Sentry et à l'importation de cartes de sources, et vous obtenez un flux de travail où les erreurs pointent toujours vers les utilisateurs code qui exécutent exactement.