문제 해결

Capgo 사용 시 발생할 수 있는 일반적인 문제와 해결 방법을 소개합니다

업로드 실패

번들 업로드가 실패하면 다음 사항을 확인하세요:

• capacitor.config.ts의 앱 ID가 Capgo 대시보드의 앱과 일치하는지
• Capacitor 프로젝트 루트에서 업로드 명령을 실행하는지
• 웹 에셋이 빌드되어 최신 상태인지

고급 업로드 옵션

Capgo CLI는 일반적인 업로드 문제를 해결하기 위한 추가 플래그를 제공합니다:

• --tus: 대용량 번들이나 불안정한 네트워크 연결에서 더 안정적인 업로드를 위해 tus 재개 가능 업로드 프로토콜을 사용합니다. 번들이 10MB 이상이거나 연결이 불안정한 경우 --tus 사용을 고려하세요:

  npx @capgo/cli@latest upload --tus

• --package-json과 --node-modules: 모노레포나 npm 워크스페이스와 같은 비표준 구조를 사용하는 경우 루트 package.json과 node_modules의 위치를 Capgo에 알려줍니다. 루트 package.json과 --node-modules 경로를 전달하세요:

  npx @capgo/cli@latest upload --package-json=path/to/package.json --node-modules=path/to/node_modules

  Capgo는 앱의 종속성을 올바르게 번들링하기 위해 이 정보가 필요합니다

이러한 플래그는 --channel과 같은 다른 옵션과 함께 사용할 수 있습니다. 사용 가능한 모든 업로드 옵션은 Capgo CLI 문서를 참조하세요

업로드에 문제가 계속되면 Capgo 지원팀에 문의하세요

업데이트 디버깅

라이브 업데이트에 문제가 있다면 Capgo 디버그 명령이 문제 해결에 도움이 됩니다. 사용 방법:

1. 프로젝트 디렉토리에서 다음 명령을 실행하세요:

   npx @capgo/cli@latest app debug

2. 기기나 에뮬레이터에서 앱을 실행하고 업데이트를 트리거할 동작을 수행하세요(예: 새 번들 업로드 후 앱 재실행)

3. 디버그 명령의 출력을 확인하세요. 다음과 같은 업데이트 프로세스 정보가 기록됩니다:

   • 앱이 업데이트를 확인하는 시점
   • 업데이트가 발견되었는지와 어떤 버전인지
   • 업데이트의 다운로드 및 설치 진행 상황
   • 업데이트 과정에서 발생하는 오류

4. 디버그 로그를 사용해 문제가 발생하는 위치를 파악하세요. 예:

   • 업데이트가 발견되지 않으면 번들이 성공적으로 업로드되었는지, 앱이 올바른 채널을 사용하도록 구성되었는지 확인
   • 업데이트가 다운로드되지만 설치되지 않으면 CapacitorUpdater.notifyAppReady()를 호출했는지, 앱이 완전히 종료되고 다시 열렸는지 확인
   • 오류 메시지가 표시되면 Capgo 문서에서 해당 오류를 찾아보거나 지원팀에 도움을 요청

디버그 명령은 특히 업데이트 다운로드 및 설치 프로세스의 문제를 파악하는 데 유용합니다. 로그에 예상된 업데이트 버전이 발견되었지만 최종적으로 적용되지 않은 것으로 나타나면 다운로드 이후 단계에서 문제 해결에 집중하세요

네이티브 로그로 디버깅하기

Capgo 디버그 명령 외에도 Android와 iOS의 네이티브 로그는 특히 업데이트 프로세스의 네이티브 측면에서 발생하는 문제에 대해 중요한 문제 해결 정보를 제공할 수 있습니다

Android 로그

Android 로그에 접근하는 방법:

1. 기기를 연결하거나 에뮬레이터를 시작하세요
2. Android Studio를 열고 “View > Tool Windows > Logcat”을 선택하세요
3. Logcat 창에서 상단 드롭다운에서 앱의 프로세스를 선택하여 로그를 필터링하세요
4. Capgo를 포함하는 라인을 찾아 SDK 로그를 확인하세요

또는 adb logcat 명령을 사용하고 Capgo로 grep하여 로그를 필터링할 수 있습니다

Capgo SDK는 업데이트 프로세스 동안 다음과 같은 주요 이벤트를 기록합니다:

• 업데이트 확인이 시작될 때
• 업데이트가 발견되었을 때와 어떤 버전인지
• 업데이트 다운로드가 시작되고 완료될 때
• 업데이트 설치가 트리거될 때
• 네이티브 업데이트 단계에서 발생하는 오류

로그에서 볼 수 있는 일반적인 Android 관련 문제는 다음과 같습니다:

• 업데이트 다운로드를 방해하는 네트워크 연결 문제
• 업데이트 번들 저장 또는 읽기 시 파일 권한 오류
• 업데이트 번들을 위한 저장 공간 부족
• 업데이트 설치 후 앱 재시작 실패

iOS 로그

iOS 로그에 접근하는 방법:

1. 기기를 연결하거나 시뮬레이터를 시작하세요
2. Xcode를 열고 “Window > Devices and Simulators”로 이동하세요
3. 기기를 선택하고 “Open Console”을 클릭하세요
4. 콘솔 출력에서 Capgo를 포함하는 라인을 찾아 SDK 로그를 확인하세요

터미널에서 log stream 명령을 사용하고 Capgo로 grep하여 로그를 필터링할 수도 있습니다

Android와 마찬가지로 Capgo SDK는 주요 iOS 측 이벤트를 기록합니다:

• 업데이트 확인 시작 및 결과
• 다운로드 시작, 진행 상황 및 완료
• 설치 트리거 및 결과
• 네이티브 업데이트 프로세스 중 발생하는 오류

로그에서 식별할 수 있는 iOS 관련 문제는 다음과 같습니다:

• 업데이트 다운로드 시 SSL 인증서 문제
• 업데이트 다운로드를 차단하는 앱 전송 보안
• 업데이트 번들을 위한 저장 공간 부족
• 업데이트 번들을 제대로 추출하거나 적용하지 못함

두 플랫폼 모두에서 네이티브 로그는 업데이트 프로세스에 대한 더 낮은 수준의 뷰를 제공하며, 네이티브 구현에 대한 더 자세한 정보를 제공합니다. 특히 Capgo JavaScript 레이어 외부에서 발생하는 문제를 식별하는 데 유용합니다

까다로운 라이브 업데이트 문제를 해결할 때는 Capgo 디버그 로그와 네이티브 로그를 모두 캡처하는 것이 좋습니다. 두 로그를 함께 사용하면 문제를 식별하고 해결할 가능성이 가장 높아집니다

업데이트가 적용되지 않는 경우

번들을 업로드했지만 기기에서 변경 사항이 표시되지 않는 경우:

• 퀵스타트에 표시된 대로 앱 코드에서 CapacitorUpdater.notifyAppReady()를 호출했는지 확인하세요
• 기기가 인터넷에 연결되어 있고 Capgo 디버그 로그에서 업데이트가 다운로드되었는지 확인하세요
• 업데이트는 새로 실행할 때만 적용되므로 앱을 완전히 종료하고 다시 여세요
• 업데이트 적용에 문제가 있음을 나타내는 네이티브 로그의 오류를 확인하세요

업데이트 프로세스에 대한 자세한 내용은 라이브 업데이트 배포 가이드를 참조하세요. 여전히 문제가 있다면 npx @capgo/cli@latest app debug 명령과 네이티브 로그를 사용하여 무슨 일이 일어나고 있는지 더 자세히 확인하세요

SDK 설치

Capgo SDK 설치에 문제가 있다면 다음을 확인하세요:

• 앱이 지원되는 버전의 Capacitor(4.0 이상)를 사용하고 있는지
• SDK 설치 후 앱 동기화를 포함하여 퀵스타트 단계를 순서대로 따랐는지

CI/CD 통합

CI/CD 파이프라인에서 Capgo 업로드 트리거에 문제가 있는 경우:

• Capgo 인증 토큰이 올바르게 설정되어 있는지 다시 확인하세요
• 웹 에셋이 빌드된 후 업로드 명령을 실행하는지 확인하세요
• 업로드 명령이 대상 환경에 맞는 채널 이름을 사용하고 있는지 확인하세요

자세한 문제 해결 팁은 CI/CD 통합 문서를 참조하세요. npx @capgo/cli@latest app debug 명령을 사용하여 CI/CD로 트리거된 업데이트가 앱에 수신되고 있는지도 확인할 수 있습니다