Relatório de erros de JavaScript do React Native

Por padrão, o agente New Relic React Native captura erros de JavaScript e rejeições de promessas não tratadas e os relata como eventosMobileJSError . É possível visualizar esses erros na interface monitoramento de mobile, consultá-los com NRQL e representá-los em gráficos nos dashboards.

Para tornar o stack trace nos eventos MobileJSError legível por humanos, o agente precisa do source map que corresponde ao pacote JavaScript em execução no aplicativo. Quando a chave de API do usuário e o token do aplicativo da New Relic são configurados corretamente, o agente faz o upload do source map automaticamente após cada build. Se não for possível fazer o upload automaticamente, ou se atualizações apenas de JavaScript forem enviadas com o CodePush ou outro serviço over-the-air (OTA), é possível fazer o upload dos source maps manualmente.

Configurar o upload automático de source map

Para fazer o upload de source maps automaticamente, forneça a chave de API de usuário do New Relic e o token do aplicativo. Como um aplicativo React Native é compilado separadamente para cada plataforma, a chave é configurada de forma diferente no Android e no iOS. Configure-o para cada plataforma fornecida.

Antes de iniciar, obtenha o seguinte da mesma conta da New Relic:

• Uma chave de API do usuário.
• O token do aplicativo mobile (o mesmo token passado para NewRelic.startAgent()).

Android

Adicione a chave de API de usuário ao arquivo newrelic.properties no projeto:

com.newrelic.api_key=<YOUR_USER_API_KEY>

Substitua <YOUR_USER_API_KEY> pela chave de API de usuário. O agente já conhece o token do aplicativo de NewRelic.startAgent(). Quando ambos os valores são válidos, o agente gera e faz o upload do source map do Android para o New Relic automaticamente após cada build de lançamento.

iOS

No iOS, um script de fase de compilação (upload-react-native-sourcemap) incluído na pasta dsym-upload-tools — a mesma pasta usada para uploads de dSYM — faz o upload do mapa de origem. A chave de API de usuário e o token do aplicativo são passados como argumentos para esse script.

1. Se os uploads de dSYM ainda não tiverem sido configurados, copie a pasta dsym-upload-tools para o SRCROOT do projeto (geralmente a pasta ios).

2. No Xcode, selecione o destino, abra a guia Build Phases e adicione um New Run Script Build Phase. Arraste-o para ser executado após a fase "Bundle React Native code and images".

3. Adicione o seguinte ao script de execução, substituindo os espaços reservados pela chave de API de usuário e pelo token do aplicativo:

   bash

   Copiar

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

O script do iOS é executado apenas para builds Release e ignora builds de simulador. Se algum dos valores estiver ausente ou for inválido, o agente não fará o upload do source map, e o stack trace de erros do JavaScript permanecerá sem simbolização. Nesse caso, faça o upload do source map manualmente.

Carregar manualmente um mapa de origem

É possível fazer o upload de um source map diretamente para a API de ingestão de símbolos do New Relic. Isso é útil quando o upload automático não é possível, ou quando são lançadas atualizações apenas de JavaScript por meio do CodePush ou de outros serviços OTA.

Use o seguinte modelo 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"

Substitua o seguinte:

• $NR_USER_API_KEY é uma chave de API de usuário da New Relic válida.
• $NR_APP_TOKEN é o seu token de monitoramento de aplicativo Mobile.
• <JS_BUNDLE_ID> é o identificador de compilação exclusivo relatado pelo agente para a sessão JavaScript (consulte Recuperar o jsBundleId).
• appVersion é a versão do aplicativo nativo de destino do pacote (por exemplo, 1.0.5).

Referência da API de upload

Endpoint

Cabeçalhos

Corpo da solicitação (dados de formulário multipart)

Respostas

As respostas usam 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"
  }
}

Faça upload de source maps para atualizações do CodePush e OTA

Ao usar o CodePush ou outro serviço de atualização OTA, a versão do pacote JavaScript diverge da versão do binário nativo. Sempre que enviar uma atualização JavaScript, é necessário fazer o upload do novo mapa de origem para que os eventos MobileJSError permaneçam legíveis na New Relic.

Para simbolizar uma atualização OTA, o upload deve usar:

• Um jsBundleId exclusivo que corresponde ao ID que o agente relata durante a sessão JavaScript.
• O appVersion correto, que é a versão nativa que o pacote tem como destino.

É possível fazer upload do source map com um script no pipeline de CI/CD ou manualmente com cURL.

Método 1: upload automatizado via script

A New Relic fornece um script auxiliar do Node.js que pode ser executado no pipeline de CI/CD imediatamente após o 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: upload manual via cURL

Caso prefira não usar o script, faça o upload do mapa de origem (descompactado ou compactado) para a API de ingestão de símbolos com 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 obter a lista completa de cabeçalhos, campos de corpo e respostas, consulte a referência da API de upload.

Recuperar o jsBundleId

O jsBundleId usado para o upload deve corresponder ao ID do pacote que o agente relata para a sessão JavaScript. Para lançamentos do CodePush, use a implantação do CodePush ou o identificador de lançamento como o jsBundleId para que o mapa de origem carregado seja mapeado para o pacote em execução nos aplicativos dos usuários.

Limitações de tamanho de arquivo

Os arquivos de mapa de origem devem ter menos de 200 MB descompactados para serem armazenados para simbolização.

Nossos scripts de build compactam automaticamente o arquivo .map com gzip antes do upload para reduzir o tamanho da transferência, mas o build verifica o limite de 200 MB em relação ao arquivo descompactado. Se o arquivo .map descompactado exceder 200 MB, o agente não fará o upload do arquivo, o que evita tempos limite de build e erros de ingestão.

Nesses casos, o script envia a telemetria de compilação (metadados) em vez do arquivo. Isso permite que a New Relic rastreie que uma compilação ocorreu, mesmo que a simbolização não esteja disponível para essa versão específica. Como resultado, MobileJSError eventos para essa compilação mostram stack trace não simbolizados (minificados).

Caso o mapa de origem seja maior que 200 MB descompactado, recomenda-se entrar em contato com o Suporte da New Relic ou enviar uma solicitação de recurso. Não é possível aumentar esse limite por conta própria.

Resolução de problemas de uploads de mapas de origem

Se os stack traces do MobileJSError não estiverem simbolizados, o mapa de origem pode ter excedido o limite de tamanho descompactado de 200 MB. Siga as etapas a seguir para confirmar a causa e solicitar ajuda. Para obter mais dicas de resolução de problemas e perguntas frequentes, consulte Resolução de problemas de mapas de origem do React Native e erros de JavaScript.

Confirmar se o arquivo ou a telemetria foi carregado

Um build bem-sucedido nem sempre significa um upload de arquivo bem-sucedido. Se o script de build for concluído com uma mensagem Success, mas o source map for maior que 200 MB descompactado, verifique os logs do console. Será exibida uma mensagem indicando que o agente enviou telemetria em vez do arquivo de source map.

Verifique o tamanho do arquivo descompactado

Verifique o tamanho do arquivo de source map para confirmar se está perto ou acima do limite:

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

Se o arquivo estiver próximo ou acima de 200 MB, o mapa de origem não poderá ser carregado para simbolização.

Solicitar suporte para mapas de origem grandes

Se o mapa de origem descompactado exceder o limite de 200 MB, não haverá como reduzi-lo localmente ou aumentar o limite por conta própria. Siga as instruções abaixo para nos informar que esse limite afeta o seu caso:

• Entre em contato com o Suporte da New Relic.
• Envie uma solicitação de recurso para aumentar o limite de tamanho do source map.