Reporte de errores de JavaScript de React Native

De forma predeterminada, el agente de New Relic React Native captura errores de JavaScript y rechazos de promesas no controlados y los reporta como eventosMobileJSError . Puede ver estos errores en la monitoreo de aplicaciones móvilesUI, consultarlos con NRQL y graficarlos en dashboards.

Para que el rastreo del stack en los eventos de MobileJSError sea legible para los humanos, el agente necesita el mapa de origen que corresponde al paquete de JavaScript que se ejecuta en la aplicación. Cuando configura correctamente la clave de API de usuario de New Relic y el token de la aplicación, el agente carga el mapa de origen automáticamente después de cada compilación. Si no puede realizar la carga automáticamente, o si envía actualizaciones solo de JavaScript con CodePush u otro servicio inalámbrico (OTA), puede cargar los mapas de origen manualmente.

Configurar la carga automática de mapas de origen

Para cargar los source maps automáticamente, proporcione la clave de API de usuario de New Relic y el token de la aplicación. Debido a que una aplicación de React Native se compila por separado para cada plataforma, debe configurar la clave de manera diferente en Android e iOS. Configúrelo para cada plataforma que distribuya.

Antes de comenzar, obtenga lo siguiente de la misma cuenta de New Relic:

• Una clave de API de usuario.
• El token de la aplicación móvil (el mismo token que pasa a NewRelic.startAgent()).

Android

Agregue su clave de API de usuario al archivo newrelic.properties en su proyecto:

com.newrelic.api_key=<YOUR_USER_API_KEY>

Reemplace <YOUR_USER_API_KEY> con la clave de API de usuario. El agente ya conoce el token de la aplicación de NewRelic.startAgent(). Cuando ambos valores son válidos, el agente genera y carga el mapa de origen de Android a New Relic automáticamente después de cada compilación de lanzamiento.

iOS

En iOS, un script (upload-react-native-sourcemap) de fase de compilación incluido en la carpeta dsym-upload-tools —la misma carpeta utilizada para cargas de dSYM — sube el mapa de origen. Pase la clave de API de usuario y el token de aplicación como argumentos a ese script.

1. Si aún no ha configurado las cargas de dSYM, copie la carpeta dsym-upload-tools en el SRCROOT del proyecto (generalmente la carpeta ios).

2. En Xcode, seleccione su objetivo, abra la pestaña Build Phases y agregue un New Run Script Build Phase. Arrástrelo para que se ejecute después de la fase “Bundle React Native code and images”.

3. Agregue lo siguiente al script de ejecución, reemplazando los marcadores de posición con la clave de API de usuario y el token de la aplicación:

   bash

   Copia

   $
   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"

El script de iOS se ejecuta solo para las compilaciones de Release y omite las compilaciones del simulador. Si falta alguno de los valores o no es válido, el agente no cargará el mapa de origen y los rastreos del stack de errores de JavaScript permanecerán sin simbolizar. En ese caso, cargue el mapa de origen manualmente.

Cargar manualmente un mapa de origen

Puede cargar un source map directamente en la API de ingesta de símbolos de New Relic. Esto es útil cuando la carga automática no es posible, o cuando lanza actualizaciones solo de JavaScript a través de CodePush u otros servicios OTA.

Utilice la siguiente plantilla de 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=<JS_BUNDLE_ID>" \
>
     -F "appVersion=1.0.5" \
>
     -F "sourcemapName=index.android.bundle.map"

Reemplace lo siguiente:

• $NR_USER_API_KEY es una clave de API de usuario de New Relic válida.
• $NR_APP_TOKEN es su token de aplicación de monitoreo de móviles.
• <JS_BUNDLE_ID> es el identificador de compilación único reportado por el agente para la sesión de JavaScript (consulte Retrieve the jsBundleId).
• appVersion es la versión de la aplicación nativa que el paquete tiene como objetivo (por ejemplo, 1.0.5).

Referencia de la API de carga

Extremo

Encabezados

Cuerpo de la solicitud (datos de formulario multiparte)

Respuestas

Las respuestas utilizan 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"
  }
}

Cargar mapas de origen para actualizaciones de CodePush y OTA

Cuando utiliza CodePush u otro servicio de actualización OTA, la versión del paquete de JavaScript difiere de la versión binaria nativa. Cada vez que envíe una actualización de JavaScript, cargue el nuevo mapa de origen para que los eventos MobileJSError sigan siendo legibles en New Relic.

Para simbolizar una actualización OTA, la carga debe utilizar:

• Un jsBundleId único que coincide con el ID que informa el agente durante la sesión de JavaScript.
• El appVersion correcto, que es la versión nativa que tiene como objetivo el paquete.

Puede cargar el mapa de origen con un script en el pipeline de CI/CD o manualmente con cURL.

Método 1: carga automatizada mediante script

New Relic proporciona un script auxiliar de Node.js que puede ejecutar en su pipeline de CI/CD inmediatamente después del comando 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étodo 2: carga manual a través de cURL

Si prefiere no usar el script, cargue el mapa de origen (descomprimido o comprimido) a la API de ingesta de símbolos con 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"

Para obtener la lista completa de encabezados, campos del cuerpo y respuestas, consulte la referencia de la API de carga.

Recuperar el jsBundleId

El jsBundleId utilizado para la carga debe coincidir con el ID del paquete que el agente reporta para la sesión de JavaScript. Para los lanzamientos de CodePush, utilice el despliegue de CodePush o el identificador de lanzamiento como jsBundleId para que el mapa de origen cargado se asigne al paquete que se ejecuta en las aplicaciones de los usuarios.

Limitaciones de tamaño de archivo

Los archivos de mapa de origen deben tener menos de 200 MB descomprimidos para almacenarse para la simbolización.

Nuestros scripts de compilación comprimen automáticamente en gzip el archivo .map antes de la carga para reducir el tamaño de transferencia, pero la compilación verifica el límite de 200 MB con el archivo descomprimido. Si el archivo .map descomprimido supera los 200 MB, el agente no carga el archivo, lo que evita tiempos de espera de compilación y errores de ingesta.

En estos casos, el script envía telemetría (metadatos) de compilación en lugar del archivo. Esto permite a New Relic rastrear que se produjo una compilación, aunque la simbolización no esté disponible para esa versión específica. Como resultado, los eventos MobileJSError para esa compilación muestran rastreos del stack no simbolizados (minificados).

Si el source map supera los 200 MB una vez descomprimido, comuníquese con el soporte de New Relic o envíe una solicitud de característica. No hay forma de aumentar este límite por su cuenta.

Solucionar problemas de carga de mapas de origen

Si sus rastreos del stack de MobileJSError no están simbolizados, es posible que su source map haya superado el límite de tamaño sin comprimir de 200 MB. Siga los siguientes pasos para confirmar la causa y solicitar ayuda. Para obtener más consejos de resolución de problemas y preguntas frecuentes, consulte Resolución de problemas de source maps de React Native y errores de JavaScript.

Confirmar si se cargó el archivo o la telemetría

Una compilación exitosa no siempre significa una carga de archivo exitosa. Si el script de compilación se completa con un mensaje Success pero el mapa de origen tiene más de 200 MB sin comprimir, revise los logs de la consola. Verá un mensaje que indica que el agente envió telemetría en lugar del archivo de mapa de origen.

Compruebe el tamaño del archivo descomprimido

Compruebe el tamaño del archivo de mapa de origen para verificar si está cerca o por encima del límite:

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

Si el archivo se acerca o supera los 200 MB, el mapa de origen no se puede cargar para la simbolización.

Solicitar soporte para mapas de origen grandes

Si el mapa de origen descomprimido supera el límite de 200 MB, no hay forma de reducirlo por su cuenta ni de aumentar el límite. Haga lo siguiente para informarnos que este límite le afecta:

• Contacte al Soporte de New Relic.
• Envíe una solicitud de característica para aumentar el límite de tamaño del mapa de origen.