Signalement des erreurs JavaScript React Native

Par défaut, l’agent New Relic React Native capture les erreurs JavaScript et les rejets de promesses non gérés, et les signale comme des événementsMobileJSError . Vous pouvez afficher ces erreurs dans l’interface utilisateur monitoring d'applications mobiles, effectuer des requêtes sur celles-ci avec NRQL, et les représenter graphiquement dans des dashboards.

Pour rendre les traces d’appels dans les événements MobileJSError lisibles par un humain, l’agent a besoin du source map qui correspond au bundle JavaScript exécuté dans votre application. Lorsque vous configurez correctement votre clé API utilisateur New Relic et votre jeton d’application, l’agent téléverse le source map pour vous automatiquement après chaque build. Si vous ne pouvez pas effectuer de téléversement automatique, ou si vous publiez des mises à jour uniquement JavaScript avec CodePush ou un autre service over-the-air (OTA), vous pouvez téléverser les source maps manuellement.

Configurer le téléversement automatique du source map

Pour téléverser automatiquement les source maps, fournissez votre clé API utilisateur New Relic et votre jeton d'application. Puisqu'une application React Native est compilée séparément pour chaque plateforme, vous configurez la clé différemment sur Android et iOS. Configurez-la pour chaque plateforme que vous livrez.

Avant de commencer, obtenez les éléments suivants à partir du même compte New Relic :

• Une clé API utilisateur.
• Votre jeton d’application mobile (le même jeton que vous passez à NewRelic.startAgent()).

Android

Ajoutez votre clé API utilisateur au fichier newrelic.properties de votre projet :

com.newrelic.api_key=<YOUR_USER_API_KEY>

Remplacez <YOUR_USER_API_KEY> par votre clé API utilisateur. L’agent connaît déjà le jeton d’application à partir de NewRelic.startAgent(). Lorsque les deux valeurs sont valides, l’agent génère et téléverse automatiquement la source map Android vers New Relic après chaque build de sortie.

iOS

Sur iOS, un script de phase de build (upload-react-native-sourcemap) inclus dans le dossier dsym-upload-tools — le même dossier utilisé pour les téléversements de dSYM — téléverse la source map. Vous passez la clé API utilisateur et le jeton d’application comme arguments à ce script.

1. Si vous n’avez pas encore configuré les téléversements dSYM, copiez le dossier dsym-upload-tools dans le SRCROOT de votre projet (généralement votre dossier ios).

2. Dans Xcode, sélectionnez votre cible, ouvrez l'onglet Build Phases et ajoutez un New Run Script Build Phase. Faites-le glisser pour l'exécuter après la phase « Bundle React Native code and images ».

3. Ajoutez ce qui suit au script d’exécution, en remplaçant les espaces réservés par votre clé API utilisateur et votre jeton d’application :

   bash

   Copier

   $
   ARTIFACT_DIR="${BUILD_DIR%Build/*}"
   $
   SCRIPT=`/usr/bin/find "${SRCROOT}" "${ARTIFACT_DIR}" -type f -name upload-react-native-sourcemap | head -n 1`
   $
   /bin/sh "${SCRIPT}" "YOUR_USER_API_KEY" "YOUR_APP_TOKEN"

Le script iOS s’exécute uniquement pour les builds Release et ignore les builds de simulateur. Si l’une des valeurs est manquante ou non valide, l’agent ne téléversera pas la source map, et les traces d’appels d’erreurs JavaScript resteront non symbolisées. Dans ce cas, téléversez la source map manuellement.

Téléchargez manuellement une carte source

Vous pouvez importer une source map directement dans l’API d’ingestion de symboles New Relic. Cela est utile lorsque l’import automatique n’est pas possible, ou lors de la sortie de mises à jour uniquement JavaScript via CodePush ou d’autres services OTA.

Utilisez le modèle cURL suivant :

$
curl -X POST "https://symbol-ingest-api.service.newrelic.com/v1/react-native/sourcemaps" \
>
     -H "Api-Key: $NR_USER_API_KEY" \
>
     -H "X-APP-LICENSE-KEY: $NR_APP_TOKEN" \
>
     -F "sourcemap=@./index.android.bundle.map" \
>
     -F "jsBundleId=<JS_BUNDLE_ID>" \
>
     -F "appVersion=1.0.5" \
>
     -F "sourcemapName=index.android.bundle.map"

Remplacez ce qui suit :

• $NR_USER_API_KEY est une clé API utilisateur New Relic valide.
• $NR_APP_TOKEN est votre jeton d'application de monitoring mobile
• <JS_BUNDLE_ID> est l’identifiant de build unique signalé par l’agent pour la session JavaScript (voir Récupérer le jsBundleId).
• appVersion est la version de l’application native que le bundle cible (par exemple, 1.0.5).

Référence de l’API de téléversement

Point de terminaison

En-têtes

Corps de la requête (données de formulaire multipart)

Réponses

Les réponses utilisent Content-Type: application/json.

{
  "sourcemapMetaData": {
    "entityGuid": "<SOURCEMAP_ENTITY_GUID>",
    "accountId": "<YOUR_ACCOUNT_ID>",
    "applicationId": "<YOUR_APPLICATION_ID>",
    "sourcemapName": "app.min.js.map",
    "appVersion": "12424",
    "JSBundleId": "87124712",
    "createdAt": "2025-11-27T10:32:44.586Z"
  }
}

Importez les source maps pour les mises à jour CodePush et OTA

Lorsque vous utilisez CodePush ou un autre service de mise à jour OTA, la version du bundle JavaScript diverge de la version binaire native. Chaque fois que vous publiez une mise à jour JavaScript, téléversez la nouvelle source map afin que les événements MobileJSError restent lisibles dans New Relic.

Pour symboliquer une mise à jour OTA, le téléversement doit utiliser :

• Un jsBundleId unique qui correspond à l’ID que l’agent signale pendant la session JavaScript.
• Le appVersion correct, qui est la version native que le bundle cible.

Vous pouvez importer la source map avec un script dans votre pipeline CI/CD ou manuellement avec cURL.

Méthode 1 : téléversement automatisé via un script

New Relic fournit un script d’assistance Node.js que vous pouvez exécuter dans votre pipeline CI/CD immédiatement après la commande appcenter codepush release-react.

$
# Example integration
$
appcenter codepush release-react -a <Owner>/<App>
$
node upload-nr-sourcemap.js --bundle android/index.android.bundle --map android/index.android.bundle.map --bundleId <NEW_ID>

Méthode 2 : téléversement manuel via cURL

Si vous préférez ne pas utiliser le script, téléversez la source map (décompressée ou compressée) vers l’API d’ingestion de symboles avec cURL :

$
curl -X POST "https://symbol-ingest-api.service.newrelic.com/v1/react-native/sourcemaps" \
>
     -H "Api-Key: $NR_USER_API_KEY" \
>
     -H "X-APP-LICENSE-KEY: $NR_APP_TOKEN" \
>
     -F "sourcemap=@./index.android.bundle.map" \
>
     -F "jsBundleId=CODE_PUSH_ID_HERE" \
>
     -F "appVersion=1.0.5" \
>
     -F "sourcemapName=index.android.bundle.map"

Pour obtenir la liste complète des en-têtes, des champs de corps, et des réponses, consultez la référence de l’API d’upload.

Récupérer le jsBundleId

Le jsBundleId utilisé pour le téléversement doit correspondre à l’ID de bundle que l’agent rapporte pour la session JavaScript. Pour les sorties CodePush, utilisez le déploiement CodePush ou l’identifiant de sortie comme jsBundleId afin que la carte source téléversée corresponde au bundle s’exécutant dans les applications de vos utilisateurs.

Limites de taille de fichier

Les fichiers source map doivent faire moins de 200 Mo une fois décompressés pour être stockés pour la symbolication.

Nos scripts de build compressent automatiquement le fichier .map au format gzip avant le téléversement pour réduire la taille du transfert, mais le build vérifie la limite de 200 Mo par rapport au fichier décompressé. Si le fichier .map décompressé dépasse 200 Mo, l’agent ne téléverse pas le fichier, ce qui évite les dépassements de délai de build et les erreurs d’ingestion.

Dans ces cas, le script envoie la télémétrie de build (métadonnées) au lieu du fichier. Cela permet à New Relic de suivre le fait qu’un build a eu lieu, même si la symbolication n’est pas disponible pour cette version spécifique. Par conséquent, les événements MobileJSError pour ce build affichent des traces d’appels non symboliquées (minifiées).

Si votre source map fait plus de 200 Mo décompressé, contactez l’assistance New Relic ou soumettez une demande de fonctionnalité. Il n’y a aucun moyen d’augmenter cette limite vous-même.

Dépanner les téléversements de source map

Si vos traces d’appels MobileJSError ne sont pas symbolisées, votre source map a peut-être dépassé la limite de taille de 200 Mo décompressée. Suivez les étapes suivantes pour confirmer la cause et demander de l’aide. Pour plus de conseils de dépannage et de questions fréquentes, consultez Dépanner les source maps React Native et les erreurs JavaScript.

Confirmez si le fichier ou la télémétrie a été téléversé

Un build réussi ne signifie pas toujours un téléversement de fichier réussi. Si votre script de build se termine par un message Success mais que votre source map fait plus de 200 Mo décompressé, vérifiez les logs de votre console. Vous verrez un message indiquant que l’agent a envoyé de la télémétrie au lieu du fichier source map.

Vérifiez la taille du fichier décompressé

Vérifiez la taille de votre fichier source map pour vérifier si vous êtes proche ou au-dessus de la limite :

$
# Check the size of the unzipped source map
$
ls -lh index.android.bundle.map

Si le fichier est proche ou supérieur à 200 Mo, la source map ne peut pas être importée pour la symbolication.

Demander la prise en charge des source maps volumineuses

Si votre source map décompressée dépasse la limite de 200 Mo, il n’y a aucun moyen de la réduire de votre côté ou d’augmenter la limite vous-même. Procédez comme suit pour nous faire savoir que cette limite vous affecte :

• Contactez le support New Relic.
• Soumettez une demande de fonctionnalité pour augmenter la limite de taille de votre source map.