트러블슈팅 (Troubleshooting)
Test Solution SDK 연동 중 예상치 못한 문제가 발생했나요? 이 문서는 일반적인 문제들을 스스로 진단하고 해결하는 데 도움을 주기 위해 만들어졌습니다. 아래 단계를 순서대로 따라 확인해 보세요.
1단계: SDK 내부 로그 활성화
문제 해결의 가장 첫 번째이자 가장 중요한 단계는 SDK가 보내는 로그를 확인하는 것입니다. startTest 호출 시 enableHostLogging 옵션을 true로 설정하여 Host 앱에서 SDK의 내부 동작 상태 및 오류 메시지를 직접 확인할 수 있습니다.
// Android (Kotlin) 예시
val options = mapOf(
"goodsId" to "[GOODS_ID]",
"suid" to "[SUID]",
"language" to "[LANGUAGE]",
"enableHostLogging" to true // 👈 이 옵션을 활성화하세요!
)
channel.invokeMethod("startTest", options)
// iOS (Swift) 예시
let options: [String: Any] = [
"goodsId": "[GOODS_ID]",
"suid": "[SUID]",
"language": "[LANGUAGE]",
"enableHostLogging": true // 👈 이 옵션을 활성화하세요!
]
channel.invokeMethod("startTest", arguments: options)
로그는 Android의 Logcat 또는 iOS의 Console(Xcode) 에서 확인할 수 있습니다. 로그 필터에 SDK를 입력하면 SDK가 출력하는 로그만 쉽게 확인할 수 있습니다.
2단계: 문제 유형별 체크리스트
활성화된 로그를 바탕으로 아래 문제 유형별 체크리스트를 확인해 보세요.
A. Android 빌드 실패: Flutter module 임포트 시 Kotlin 버전 충돌
Android 네이티브 프로젝트에 SDK 모듈을 추가한 후, 앱 빌드 시 다음과 유사한 IllegalArgumentException: source must not be null 오류가 발생할 수 있습니다.
-
문제 현상:
app/build.gradle.kts파일에 SDK 의존성을 추가하면 아래와 같은 오류 메시지와 함께 빌드가 실패합니다.// app/build.gradle.kts
dependencies {
// ...
debugImplementation("com.mscbrain.sdk.test_solution.test_solution_sdk:flutter_debug:1.0")
// ...
} -
오류 로그 예시:
org.jetbrains.kotlin.util.FileAnalysisException: While analysing ... ????.kt
...
Caused by: java.lang.IllegalArgumentException: source must not be null
at org.jetbrains.kotlin.diagnostics.KtDiagnosticReportHelpersKt.requireNotNull(...)
at org.jetbrains.kotlin.fir.analysis.checkers.expression.FirIncompatibleClassExpressionChecker.checkSourceElement(...) -
원인: 이 문제의 주된 원인은 Android 네이티브 프로젝트가 사용하는 Kotlin 컴파일러 버전과 SDK를 빌드할 때 사용된 Kotlin 컴파일러 버전이 서로 호환되지 않기 때문입니다. 저희 SDK는 최소 2.1.0 버전의 Kotlin을 필요로 합니다. 만약 안드로이드 프로젝트의 Kotlin 버전이 이보다 낮을 경우, 컴파일러가 SDK의 클래스 메타데이터를 올바르게 해석하지 못해 빌드 과정에서 충돌이 발생합니다.
-
해결 방법: 프로젝트의 Kotlin 버전을 SDK 요구사항에 맞게
2.1.0이상으로 업그레이드해야 합니다.
B. 테스트 화면이 나타나지 않거나 앱이 중단(Crash)될 때
- 네이티브 연동 설정 확인: Android 설정 및 iOS 설정 문서에 따라 모든 네이티브 설정이 정확하게 완료되었는지 다시 한번 확인하세요. 특히 Flutter Engine 초기화 코드가 누락되지 않았는지 확인해야 합니다.
- SDK 버전 호환성: Host 앱의 Flutter 버전과 SDK가 빌드된 Flutter 버전 간의 호환성 문제가 있을 수 있습니다. SDK 릴리즈 노트를 확인해 주세요.
C. 화면이 검은색 또는 흰색으로만 표시될 때 (콘텐츠 로딩 실패)
이 문제는 주로 테스트 문항 정보를 불러오지 못했을 때 발생합니다.
- 필수 파라미터 확인:
goodsId,suid,language값이null이거나 비어있지 않은지 확인하세요. 필수 값이 누락되면 SDK가 정상적으로 초기화되지 않을 수 있습니다. SDK 로그를 확인해보세요. - 네트워크 연결 상태: 디바이스가 인터넷에 연결되어 있는지 확인하세요.
- 인터넷 권한:
- Android:
AndroidManifest.xml에android.permission.INTERNET권한이 포함되어 있는지 확인하세요. - iOS:
Info.plist에 App Transport Security 설정이 올바르게 구성되어 있는지 확인하세요. (http 통신일 경우)
- Android:
D. UI 커스터마이징이 적용되지 않을 때
- 파라미터 이름 확인:
themeColor,themeMode,titleText등 옵션의 파라미터 이름이 정확한지 확인하세요. (오타 주의) themeColor형식 확인: 색상 값은 반드시0xAARRGGBB(알파, 레드, 그린, 블루) 또는0xRRGGBB(레드, 그린, 블루) 형식의 숫자형이어야 합니다.themeMode값 확인:themeMode는 정확히'light'또는'dark'또는'system'여야 합니다. 다른 문자열은 무시됩니다.
E. onResult, onLog, onInfo 콜백이 호출되지 않을 때
onLog콜백:startTest시enableHostLogging옵션이true로 설정되어 있는지 다시 확인하세요.onResult콜백:onResult콜백은 주로 사용자와 상호작용이 발생했을때 호출됩니다.onInfo콜백:onInfo콜백은getSDKVersionMethodChannel을 호출할 때 호출됩니다.- 네이티브 콜백 핸들러 구현: Host 앱의 네이티브 코드에 콜백을 수신하여 처리하는 로직이 올바르게 구현되었는지 콜백 처리하기 문서를 참고하여 확인하세요.
3단계: 그래도 문제가 해결되지 않는다면
위의 모든 단계를 확인했음에도 문제가 지속된다면, 지원 채널에 문의하기 전에 아래 정보를 준비해 주세요. 정확한 정보는 문제 해결 시간을 크게 단축시킬 수 있습니다.
- 사용 중인 SDK 버전: (예:
1.2.1+10201) - 테스트 환경: (예:
Android 13 / Samsung Galaxy S23,iOS 17.2 / iPhone 15 Pro) - 문제 상황에 대한 상세한 설명:
- 어떤 동작을 시도했나요?
- 무엇을 기대했나요?
- 실제 결과는 어땠나요?
enableHostLogging을 활성화하여 수집한 전체 로그startTest를 호출하는 부분을 포함한 Host 앱의 관련 코드 스니펫
준비된 정보를 담당자 또는 지정된 기술 지원 채널로 전달해 주세요.