SDK 문제 해결
에뮬레이터에서 빠르게 확인하기
저장소의 샘플 앱은 로컬 서버와 SDK 흐름을 확인하는 도구입니다. 개발자 콘솔에서 앱을 등록할 때 callback으로 opentester-sample://callback을 추가하고, 테스터 계정의 앱 참여를 승인합니다.
Android SDK와 JDK를 준비한 뒤 저장소 루트에서 실행합니다.
cd opentester-android-sdk
./gradlew :opentester:testDebugUnitTest :sample:assembleDebug
adb install -r sample/build/outputs/apk/debug/sample-debug.apkadb가 PATH에 없다면 Android SDK의 platform-tools/adb를 사용합니다. 샘플의 기본 주소는 웹 http://10.0.2.2:3000, API http://10.0.2.2:4000입니다. API 서버의 허용 Origin에 샘플이 여는 웹 주소가 포함되어야 합니다.
- 샘플에 콘솔의 앱 ID를 입력합니다.
- 브라우저 로그인 버튼을 누르고 승인된 테스터 계정으로 로그인합니다.
- 앱 연결을 승인하고 샘플로 돌아옵니다.
- 현재 권한 확인과 버그·개선 의견 제출을 실행합니다.
- 개발자 콘솔에서 보고서가 생성되었는지 확인합니다.
실제 USB 기기에서 로컬 서버를 사용할 때는 다음을 실행하고 샘플 주소를 http://localhost:3000, http://localhost:4000으로 바꿀 수 있습니다.
adb reverse tcp:3000 tcp:3000
adb reverse tcp:4000 tcp:4000샘플은 debug manifest에서만 로컬 HTTP와 custom callback을 허용합니다. 실제 배포 앱은 HTTPS App Links를 구성합니다.
로그인 화면은 열리지만 앱으로 돌아오지 않아요
- 콘솔의 callback,
OpenTesterConfig.redirectUri, manifest의 host/path가 같은지 확인합니다. - callback 도메인의
assetlinks.json에 설치된 앱의 application ID와 서명 인증서 지문이 있는지 확인합니다. - callback을 받는 Activity가
exported="true"이고VIEW,DEFAULT,BROWSABLE을 선언했는지 확인합니다. - 샘플 custom scheme은 로컬 개발 설정에서만 사용합니다. 배포 API는 HTTPS callback을 요구합니다.
“진행 중인 로그인이 없습니다” 또는 state 오류가 나요
로그인을 시작한 SDK 인스턴스로 callback을 처리해야 합니다. 인스턴스를 Application이나 유지되는 객체에 두세요. 프로세스가 종료되었다면 로그인부터 다시 시작합니다.
callback은 한 번만 처리하고 Intent의 data를 비웁니다. createAuthenticationUri()를 중복 호출하면 진행 중 state가 교체됩니다. callback 교환 중 오류나 취소가 발생해도 새 로그인을 시작하세요.
401 또는 403이 나요
| 응답 | 점검할 내용 |
|---|---|
401 | 로그인 코드가 만료·소비되었거나 토큰이 만료되었는지 확인하고 재로그인 |
403 | 해당 앱의 참여 상태가 approved인지 확인 |
기기의 브라우저 계정은 데스크톱 브라우저와 다를 수 있습니다. 앱 소유자 계정과 테스터 계정을 혼동하지 않았는지 확인하세요. Google Group 가입만으로 앱별 SDK 참여 권한이 생기지는 않습니다.
승인 철회 후 새 요청은 실패하는 것이 정상입니다. 401·403 이후 SDK의 메모리 세션도 지워집니다.
네트워크 오류 또는 잘못된 응답이 나요
apiBaseUrl에/api/v1을 중복해서 붙이지 않았는지 확인합니다.webBaseUrl은 API 서버가 아닌 OpenTester 웹 주소여야 합니다.- Android 에뮬레이터에서 개발 머신에 연결하려면
10.0.2.2를 사용합니다. - 로컬 HTTP에는 SDK의
allowInsecureLocalhost = true와 Android debug 네트워크 보안 설정이 모두 필요합니다. SDK는 임의 LAN HTTP 주소를 허용하지 않습니다. - 프록시가 API 요청을 HTML 로그인 화면으로 보내거나 redirect하는지 확인합니다. SDK는 redirect를 따라가지 않습니다.
연결 timeout은 10초, 읽기 timeout은 15초입니다. 오프라인에서 권한 확인을 성공한 것으로 처리하지 않습니다.
재시도했더니 같은 보고서가 돌아와요
같은 앱·테스터·clientRequestId로 제출하면 기존 결과를 반환합니다. 이는 중복 생성 방지 동작입니다. 기존 UUID에 다른 내용을 전달해도 수정되지 않습니다. 새 보고서는 새 UUID를, 전송 실패의 재시도는 이전 UUID를 사용하세요.
반대로 중복 보고서가 만들어진다면 재시도 때마다 BugReport나 FeedbackReport를 새로 생성하고 있는지 확인합니다. 재시도 가이드를 참고하세요.
오류가 자동으로 제출되지 않아요
현재 SDK는 submitBug() 또는 submitFeedback() 호출에 의한 텍스트 제출을 지원합니다. uncaught exception 수집, 자동 충돌 제출, 첨부, 세션 녹화, 오프라인 큐는 구현되어 있지 않습니다.
Maven 의존성을 찾을 수 없어요
Maven Central 좌표는 app.opentester:android-sdk:0.1.0입니다. settings.gradle.kts의 의존성 저장소에 mavenCentral()이 있는지 확인하세요. Kotlin 패키지인 dev.opentester.sdk와 Maven group ID는 다릅니다. JitPack을 사용한다면 저장소 https://jitpack.io와 좌표 com.github.opentesterapp:opentester-android-sdk:v0.1.0을 함께 설정하세요.
릴리스 빌드가 SDK 클래스를 찾지 못해요
debugImplementation을 사용하면 release에서는 SDK를 참조할 수 없습니다. 테스트용 Activity·Application·manifest를 src/debug/ 또는 해당 테스트 flavor의 source set에 두고, 공통 코드에는 빌드별 구현을 주입하세요. 제공된 샘플은 SDK 검증용 앱이며 일반 사용자용 배포 템플릿은 아닙니다.