Guide d'intégration 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 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 nomination de la version de sortie, et garder tout cela aligné lorsque votre modèle de livraison inclut des mises à jour en temps réel.

La plupart des guides s'arrêtent trop tôt. Un réel setup doit survivre aux CI, aux builds de l'App Store, aux sorties Android et aux bundles JavaScript qui ne viennent pas toujours du binaire 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 natifs iOS et Android
  • Ce qui a changé sur iOS
  • Ce qui a changé sur Android
  • Vérifications de mise en place native 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 résoudre les problèmes de votre intégration
  • Déclencher des événements de test de manière sécurisée
  • Quels éléments vérifier dans l'interface utilisateur de Sentry
  • Résolution des problèmes courants de Sentry React Native
• 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 meilleure façon de mettre en place Sentry React Native dans une nouvelle application est toujours le guide d'installation. Il gère la plupart 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 l'installation initiale 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 le suivi de votre processus de mise en production et de mise à jour d'un code partagé.

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

npx @sentry/wizard@latest -i reactNative

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

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

Exécuter le sorcier et examiner les résultats

Après que le sorcier se soit terminé, inspectez les modifications au lieu de les faire confiance sans examen. Vous devriez voir un package Sentry dans package.jsonchangements natifs sous ios et android, et un bloc d'initialisation dans votre fichier d'entrée d'application.

Un exemple d'initialisation 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 qui doit toujours rester invisible. Ce n'est pas la même chose qu'un jeton d'authentification. Cependant, gardez votre configuration de l'environnement propre et cohérent pour que votre application pointe vers le bon projet Sentry dans chaque environnement.

A un bon usage, 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.

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. À ce stade, ne poursuivez pas la perfection. L'objectif immédiat est simple : lancer l'application, déclencher une exception JavaScript plus tard dans l'article et confirmer que les événements atteignent Sentry. Une fois cela fonctionnel, les couches natives et de version deviennent beaucoup plus faciles à raisonner.

La configuration des projets natifs iOS et Android

À ce stade, de nombreux équipes de React Native ont une fausse impression de complétion. Le JavaScript est installé, les événements apparaissent et tout le monde suppose que la mise en 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 hooks d'initialisation de Sentry et les étapes d'envoi liées à votre processus de construction.

Dans Xcode, vérifiez ces endroits :

L'initialisation de Sentry dans le démarrage de l'application

• code. La mise en œuvre native de Sentry doit être effectuée tôt dans la lancement.
• Phases de construction. Cherchez tout script d'envoi 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 de la passerelle de 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, il ne faut donc pas copier des snippets de répos aléatoires à moins qu'ils correspondent à la forme de votre projet.

C'est l'intention qui compte : les défaillances natives d'iOS nécessitent des données de symboles, et l'application doit démarrer Sentry avant que les défaillances ne puissent être observées 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 "l'envoi de symboles" ou "la correspondance de la version de release".

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 tout plugin ou tâche lié à Sentry.

Choses à vérifier :

1. Le plugin Sentry Gradle est appliqué pour que les artefacts de la mise en production soient 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 mise en production 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 mise en place de la mise en production est correcte. Ce n'est pas le cas. La voie de la mise en production 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 mise en place natives qui économisent du temps plus tard

N'arrêtez pas à « le magicien 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 entre le nom de package et l'identifiant de bundle dans Sentry si vous gérez plusieurs applications sous une seule 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 mise en place est ennuyeuse. 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

Si un endroit où les ensembles 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. Ensuite, 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 sources appartient à un bundle différent.

Les uploads de cartes de sources manuels semblent acceptables lorsque vous expédiez rarement. Dans la pratique, ils échouent car les humains sont mauvais dans la tenue de livres de version répétitive.

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 bundle OTA utilisé par les utilisateurs.
• Le nom de la version change légèrement entre les étapes iOS, Android et CI.
• Une reconstruction a lieu après téléchargement de cartes et invalide ce que Sentry devrait correspondre.

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

Un processus de versionnement qui tient vraiment

Un setup fiable a quelques propriétés :

• Les identifiants de version sont générés une fois et réutilisés partout. Les étapes de construction, de bundling et d'upload se produisent dans le même pipeline.
• Les cartes de source 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 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 que les cartes de source soient présentes 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 a déjà standardisé 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èle opérationnel. Release IDs are generated once and reused everywhere.

Build, bundle, and upload steps happen in the same pipeline Source maps are uploaded from CI, not from a developer laptop..

The app initializes Sentry with the same release string that CI used during upload. automatic build and release workflows with GitHub Actions If your team is already standardizing mobile automation, this guide to automatic build and release workflows with __CAPGO_KEEP_0__ Actions fits well with the same operational model.

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 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 normal. 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 la 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 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 ? Pendant le rendu d'un graphique lourd ? Sentry devient utile ici lorsque vous arrêtez de traiter cela comme un boîtier d'erreur et que vous commencez à instrumenter le comportement de l'application.

Traçage d'une écran lent au lieu de deviner

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

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

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

Un exemple de tableau de bord pratique :

1. Un utilisateur ouvre le tableau de bord principal après connexion.
2. La navigation est terminée, mais le contenu apparaît 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 trace.

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

Pour les équipes qui réfléchissent de manière large sur les modèles de surveillance de webview ou d'applications hybrides, cet article sur la surveillance de performances dans les projets Capacitor vaut la peine de l'écouter car l'esprit opérationnel est similaire même si le pilon diffère.

Ajoutez 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 étaient et ce qui s'est produit 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 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 à 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 de l'application à tout jamais. Capturer les limites, les transitions d'état et les opérations qui comptent lors de la déboguage. 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 lancer la mise en production, après les modifications du pipeline de construction et après les mises à jour de SDK. « Cela fonctionnait depuis 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 la façon dont 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 page 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 des 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'utilité de test de crash natif documentée de SDK lorsqu'elle est disponible plutôt que de créer mon propre chemin de crash.

Quels éléments vérifier dans l'interface utilisateur de Sentry

Quand 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.
• Release et dist. Si ils sont vides ou incorrects, les cartes de source et la symbolication dériveront.
• Fenêtres de pile. Les emplacements de source lisibles devraient apparaître pour les cartes JavaScript correctement chargées.
• Miettes 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.

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

Problèmes de dépannage React Native de Sentry

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 flux de travail d'actualisation en direct comme Capgo

Les mises à jour en direct changent le modèle de mise en production. Le 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 la mise en production de Sentry suive le paquet JavaScript en direct et non seulement le binaire natif.Correspondance des identifiants de mise en production aux paquets en direct

Pour les flux de travail 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 :

Intégrer avec les flux de travail d'actualisation en direct comme __CAPGO_KEEP_0__

• Utilisez la version de l'application native en tant que partie du nom de la version de base.
• Insérez la version de mise à jour en direct ou l'identifiant du paquet.
• Utilisez dist pour la différenciation du canal ou de la construction spécifique lorsque cela convient à votre modèle.
• Envoyez les cartes de source pour chaque paquet 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 paquet hotfixé, à Sentry de résoudre les cadres en fonction de la carte de source pour ce hotfix au lieu du paquet 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 de 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 des mauvaises mises à jour. 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 code exacts utilisateurs qui exécutent.