리액트 네이티브 자바스크립트 오류 보고

기본적으로 뉴렐릭 리액트 네이티브 에이전트는 JavaScript 오류와 처리되지 않은 프로미스 거부를 캡처하고 이를 MobileJSError 이벤트로 보고합니다. 모바일 모니터링UI에서 이러한 오류를 확인하고, NRQL로 쿼리하며, 대시보드에서 차트로 표시할 수 있습니다.

MobileJSError 이벤트의 스택 추적을 사람이 읽을 수 있도록 하려면, 앱에서 실행 중인 자바스크립트 번들에 해당하는 소스 맵이 에이전트에 필요합니다. 뉴렐릭 사용자 API 키와 애플리케이션 토큰을 올바르게 구성하면, 각 빌드 후에 에이전트가 자동으로 소스 맵을 업로드합니다. 자동으로 업로드할 수 없거나 CodePush 또는 다른 OTA(Over-The-Air) 서비스로 자바스크립트 전용 업데이트를 배포하는 경우, 소스 맵을 수동으로 업로드할 수 있습니다.

자동 소스 맵 업로드 설정

소스 맵을 자동으로 업로드하려면 뉴렐릭 사용자 API 키와 애플리케이션 토큰을 제공하십시오. 리액트 네이티브 앱은 각 플랫폼에 대해 별도로 빌드되므로 안드로이드와 iOS에서 키를 다르게 구성합니다. 배포하는 각 플랫폼에 대해 설정하십시오.

시작하기 전에 동일한 뉴렐릭 계정에서 다음을 가져오십시오:

• 사용자 API 키.
• 모바일 애플리케이션 토큰 (NewRelic.startAgent()에 전달하는 것과 동일한 토큰)입니다.

Android

프로젝트의 newrelic.properties 파일에 사용자 API 키를 추가하십시오:

com.newrelic.api_key=<YOUR_USER_API_KEY>

<YOUR_USER_API_KEY>을(를) 사용자 API 키로 바꾸십시오. 에이전트는 이미 NewRelic.startAgent()에서 애플리케이션 토큰을 알고 있습니다. 두 값이 모두 유효한 경우, 에이전트는 각 릴리스 빌드 후에 안드로이드 소스 맵을 생성하여 뉴렐릭에 자동으로 업로드합니다.

iOS

iOS에서는 dsym-upload-tools 폴더 — dSYM 업로드에 사용되는 것과 동일한 폴더 — 에 포함된 빌드 단계 스크립트(upload-react-native-sourcemap)가 소스 맵을 업로드합니다. 사용자 API 키와 애플리케이션 토큰을 해당 스크립트에 인수로 전달합니다.

1. 아직 dSYM 업로드를 설정하지 않으셨다면, dsym-upload-tools 폴더를 프로젝트의 SRCROOT (일반적으로 ios 폴더)에 복사해 주십시오.

2. Xcode에서 타겟을 선택하고 Build Phases 탭을 연 다음 New Run Script Build Phase을(를) 추가합니다. "Bundle React Native code and images" 단계 이후에 실행되도록 드래그합니다.

3. 플레이스홀더를 사용자 API 키 및 애플리케이션 토큰으로 교체하여 실행 스크립트에 다음을 추가하십시오:

   bash

   카피

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

iOS 스크립트는 Release 빌드에 대해서만 실행되며 시뮬레이터 빌드는 건너뜁니다. 두 값 중 하나라도 누락되거나 유효하지 않으면 에이전트는 소스 맵을 업로드하지 않으며, JavaScript 오류 스택 추적은 기호화되지 않은 상태로 유지됩니다. 이 경우 소스 맵을 수동으로 업로드하십시오.

수동으로 소스 맵 업로드

소스 맵을 뉴렐릭 심볼 수집 API에 직접 업로드할 수 있습니다. 이는 자동 업로드가 불가능하거나 CodePush 또는 기타 OTA 서비스를 통해 JavaScript 전용 업데이트를 배포할 때 유용합니다.

다음 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"

다음을 변경하십시오:

• $NR_USER_API_KEY 유효한 뉴렐릭 사용자 API 키입니다.
• $NR_APP_TOKEN 귀하의 모바일 모니터링 애플리케이션 토큰 입니다.
• <JS_BUNDLE_ID> 은(는) JavaScript 세션에 대해 에이전트가 보고하는 고유 빌드 식별자입니다(jsBundleId 검색 참조).
• appVersion 번들이 타겟으로 하는 네이티브 애플리케이션 버전입니다(예: 1.0.5).

업로드 API 참조

끝점

헤더

요청 본문(멀티파트 양식 데이터)

응답

응답은 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"
  }
}

CodePush 및 OTA 업데이트를 위한 소스 맵을 업로드하십시오.

CodePush 또는 다른 OTA 업데이트 서비스를 사용하는 경우 JavaScript 번들 버전이 네이티브 바이너리 버전과 달라집니다. JavaScript 업데이트를 푸시할 때마다 뉴렐릭에서 MobileJSError 이벤트를 계속 읽을 수 있도록 새 소스 맵을 업로드하십시오.

OTA 업데이트를 심볼릭화하려면 업로드에 다음을 사용해야 합니다:

• 자바스크립트 세션 동안 에이전트가 보고하는 ID와 일치하는 고유한 jsBundleId 입니다.
• 번들이 타겟으로 하는 네이티브 버전인 올바른 appVersion

CI/CD 파이프라인의 스크립트를 사용하거나 cURL을 사용하여 수동으로 소스 맵을 업로드할 수 있습니다.

방법 1: 스크립트를 통한 자동 업로드

뉴렐릭은 appcenter codepush release-react 명령 직후에 CI/CD 파이프라인에서 실행할 수 있는 Node.js 도우미 스크립트를 제공합니다.

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

방법 2: cURL을 통한 수동 업로드

스크립트를 사용하지 않으려면 cURL을 사용하여 소스 맵(압축 해제 또는 압축 상태)을 심볼 수집 API에 업로드하십시오:

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

헤더, 본문 필드 및 응답의 전체 목록은 업로드 API 참조를 확인하십시오.

jsBundleId 가져오기

업로드에 사용된 jsBundleId은(는) 에이전트가 JavaScript 세션에 대해 보고하는 번들 ID와 일치해야 합니다. CodePush 릴리스의 경우 업로드된 소스 맵이 사용자 앱에서 실행 중인 번들에 매핑되도록 CodePush 배포 또는 릴리스 식별자를 jsBundleId (으)로 사용하십시오.

파일 크기 제한

기호화를 위해 저장하려면 압축을 푼 소스 맵 파일이 200 MB 미만이어야 합니다.

빌드 스크립트는 전송 크기를 줄이기 위해 업로드 전에 .map 파일을 자동으로 gzip으로 압축하지만, 빌드는 압축을 푼 파일에 대해 200 MB 제한을 확인합니다. 압축을 푼 .map 파일이 200 MB를 초과하면 에이전트가 파일을 업로드하지 않으며, 이는 빌드 시간 초과 및 수집 오류를 방지합니다.

이러한 경우 스크립트는 파일 대신 빌드 텔레메트리(메타데이터)를 보냅니다. 이를 통해 특정 버전에 대해 심볼리케이션을 사용할 수 없는 경우에도 뉴렐릭은 빌드가 발생했음을 추적할 수 있습니다. 결과적으로 해당 빌드에 대한 MobileJSError 이벤트는 심볼리케이션되지 않은(축소된) 스택 추적을 표시합니다.

압축 해제된 소스 맵이 200MB보다 큰 경우, 뉴렐릭 지원팀에 문의하거나 기능 요청을 제출하십시오. 이 제한을 직접 늘릴 수 있는 방법은 없습니다.

소스 맵 업로드 문제 해결

MobileJSError 스택 추적이 기호화되지 않은 경우 소스 맵이 압축 해제된 크기 제한인 200MB를 초과했을 수 있습니다. 다음 단계에 따라 원인을 확인하고 도움을 요청하십시오. 더 많은 문제 진단, 해결 팁과 자주 묻는 질문은 리액트 네이티브 소스 맵 및 JavaScript 오류 문제 진단, 해결을 참조하십시오.

파일 또는 텔레메트리가 업로드되었는지 확인하십시오

성공적인 빌드가 항상 성공적인 파일 업로드를 의미하는 것은 아닙니다. 빌드 스크립트가 Success 메시지와 함께 완료되지만 압축을 푼 소스 맵이 200MB보다 큰 경우 콘솔 로그를 확인하십시오. 에이전트가 소스 맵 파일 대신 텔레메트리를 보냈음을 나타내는 메시지가 표시됩니다.

압축을 푼 파일 크기 확인

소스 맵 파일의 크기를 확인하여 한도에 근접했는지 또는 한도를 초과했는지 확인하십시오:

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

파일이 200 MB에 가깝거나 그 이상인 경우 심볼리케이션을 위해 소스 맵을 업로드할 수 없습니다.

대용량 소스 맵에 대한 지원 요청

압축 해제된 소스 맵이 200 MB 제한을 초과하는 경우, 사용자 측에서 이를 줄이거나 직접 제한을 늘릴 수 있는 방법은 없습니다. 이 제한이 귀하에게 영향을 미친다는 것을 당사에 알리려면 다음을 수행하십시오:

• 뉴렐릭 지원에 문의하십시오.
• 소스 맵 크기 제한을 늘리려면 기능 요청을 제출하십시오.