문제 해결¶
SDK 초기화 예외 검증¶
Logcat에서 Level이 Error이고 Tag가 [FT-SDK] 접두사인 로그가 있는지 확인합니다.
디버그 환경에서 Guance SDK를 구성하고 해당 애플리케이션을 처음 실행한 후 Xcode에서 디버거 콘솔을 확인하세요. SDK는 어서션을 사용하여 여러 구성의 정확성을 검사하며, 구성이 잘못된 경우 크래시가 발생하고 관련 경고를 출력합니다.
예: SDK를 구성할 때 datakit metrics 기록 주소를 설정하지 않으면 프로그램이 크래시되면서 콘솔에 경고 ⚠️를 출력합니다.
디버그 모드 활성화¶
다음 구성을 통해 SDK의 debug 기능을 활성화할 수 있습니다.
let config: FTMobileConfig = {
serverUrl: Config.SERVER_URL,
debug: true
};
FTMobileReactNative.sdkConfig(config);
Release 버전을 배포할 때 이 구성을 비활성화하는 것이 좋습니다.
Logcat에서 Tag가 [FT-SDK] 접두사인 로그를 확인합니다.
SDK의 디버그 로그는 [FTLog] 접두사로 식별됩니다.
-
Xcode에서 실행하면 Xcode 디버그 콘솔에서 SDK 디버그 로그를 직접 확인할 수 있습니다.
-
터미널 명령으로
yarn ios또는yarn react-native run-ios를 실행하는 경우 Mac의 "콘솔"에서 SDK 디버그 로그를 확인할 수 있습니다.
"콘솔" 사용 방법:
작업을 선택하고 요약 정보 포함, 디버그 정보 포함을 체크합니다.
디버그할 기기를 선택하고 시작 버튼을 클릭한 뒤 오른쪽 검색 조건 상자에 검색 조건 [FTLog] 를 입력합니다. 이제 SDK 디버그 로그를 확인할 수 있습니다.
Android Logcat 및 iOS Xcode Console 로그 예시
SDK가 정상적으로 실행되지만 데이터가 없음¶
-
Datakit이 정상적으로 실행되는지 확인합니다.
-
SDK 업로드 주소
datakitUrl또는datawayUrl이 올바르게 구성되었는지, 그리고 올바르게 초기화되었는지 확인합니다. debug 모드에서 Android Logcat 또는 iOS Xcode Console의 동기화 로그를 확인합니다. -
datakit이 해당 워크스페이스로 데이터를 업로드하는지, 오프라인 상태인지 확인합니다. 이 문제는 Guance에 로그인한 뒤 "인프라"를 확인하여 판단할 수 있습니다.
데이터 손실¶
일부 데이터 손실¶
-
RUM의 특정 Session 데이터 또는 Log, Trace의 몇몇 데이터가 손실된 경우, 먼저 FTRUMConfig, FTLogConfig, FTTraceConfig에서 100 미만의 백분율 샘플링 비율(
sessionSamplingRate,logSamplingRate,traceSamplingRate)을 설정했는지, 또는 새 필드를 구성하지 않은 상태에서sampleRate < 1을 사용했는지 확인해야 합니다. SDK 0.4.3부터 새 필드와 기존 필드를 동시에 설정하면 새 필드가 우선합니다. 자세한 내용은 샘플링 구성을 참조하세요. -
수집된 RUM 데이터가 불완전하고 Resource 또는 Action 데이터가 없나요?
Resource 및 Action 데이터는 View와 바인딩되므로
FTReactNativeRUM.startView작업이 있는지 확인해야 합니다. View 이벤트 수집을 구현하려면 RUM View 문서를 참조하세요. -
데이터를 업로드하는 기기의 네트워크와 datakit이 설치된 기기의 네트워크 및 부하 문제를 확인합니다.
호환성 문제¶
react-native-navigation 실행 호환성 문제¶
ReactTextShadowNode.UNSET 기호를 찾을 수 없음¶
이는 react-native-navigation 버전 호환성 문제로 인해 발생합니다. 관련 이슈는 여기에서 확인하세요. ReactTypefaceUtils.java를 변경하거나 다운로드하여 교체하면 이 문제를 해결할 수 있습니다.
react/jsx-runtime 모듈을 찾을 수 없음¶
영향 범위: SDK 버전 0.3.0 && React 버전 < 16.14.0
원인: SDK 내부에서 사용하는 react/jsx-runtime은 React >= 16.14.0에서만 지원됩니다.
수정 제안:
- SDK 버전을 >= 0.3.1로 업그레이드합니다.
참고: 로컬 경로 방식으로 @cloudcare/react-native-mobile 의존성 라이브러리를 추가하는 것은 권장하지 않습니다. 오류를 해결하지 못할 수 있습니다.
네이티브와 React Native 혼합 개발¶
오류: Cannot read properties of undefined (reading 'addError')¶
원인: RN SDK 버전과 네이티브 SDK 버전이 호환되지 않거나 설치가 불완전하여 발생합니다.
문제 확인 방법:
Android 프로젝트 루트 디렉터리에서 터미널에서 ./gradlew app:dependencies 명령을 실행하고, 출력 결과에 cloudcare_react-native-mobile이 포함되어 있는지 확인합니다.
cloudcare_react-native-mobile은 RN 프로젝트에서 Guance RN SDK 의존성을 추가한 후 Android 측에 설치되는 의존성 라이브러리입니다.
Podfile.lock 파일에서 FTMobileReactNativeSDK 의존성이 있는지 확인합니다.
FTMobileReactNativeSDK는 RN 프로젝트에서 Guance RN SDK를 통합한 후 iOS 측에 설치되는 의존성 라이브러리입니다.
수정 제안:
-
버전 호환성 확인
- RN SDK와 네이티브 SDK 버전이 일치하는지 확인합니다.
- RN SDK에 대응하는 네이티브 SDK 버전 정보 확인 경로:
node_modules/@cloudcare/react-native-mobile/android/build.gradlenode_modules/@cloudcare/react-native-mobile/FTMobileReactNativeSDK.podspec -
의존성 재설치
- 프로젝트 캐시 정리:
- 의존성 재설치:
위 단계를 통해 버전 비호환 또는 불완전한 설치로 인해 발생하는 이 오류를 효과적으로 해결할 수 있습니다.

