로그

이 플러그인의 설치 단계와 전체 마크다운 가이드가 포함된 설정 프롬프트를 복사하세요.

로그 및 로그 인사이트

앱 로그 탭이 열립니다 로그 인사이트 기본값입니다. Insights를 사용해 1, 3, 7, 30일 기간 동안 카테고리, 버전, 기기를 우선순위로 설정하세요. 다음으로 전환하세요. 로그 아래에 설명된 기본 디바이스 이벤트, 필터, 타임스탬프가 필요할 때 사용하는 서브탭입니다.

애플리케이션 로그 이해하기

Raw Logs 서브탭에서는 업데이트 이벤트의 상세 이력과 애플리케이션 진단 정보를 확인할 수 있습니다. Insight의 근거가 되는 디바이스 레벨의 데이터를 확인하거나, 업데이트 경로를 트러블슈팅하고, 디바이스가 Capgo와 어떻게 상호작용하는지 파악할 때 유용합니다. 앱을 열고, 로그를 선택한 다음, 로그 서브탭을 선택하세요.

메인 인터페이스를 보여주는 Raw Logs 탭 개요 — Raw Logs 탭

Raw Logs 인터페이스 구성 요소:

Logs 서브탭 — 개별 로그 행에 대한 탐색 컨트롤.
새로고침 버튼 — 최신 데이터로 로그 목록을 새로고침합니다.
시간 범위 및 액션 필터 — 시간과 액션별로 이벤트 스트림을 좁혀서 봅니다.

각 행에는 다음이 표시됩니다:

타임스탬프 (UTC)
기기 ID
액션 code (무슨 일이 발생했는지)
버전 이름 (bundle 또는 builtin)

행을 클릭하면 해당 기기의 전체 이력을 볼 수 있는 디바이스 상세 페이지로 이동합니다.

날짜 범위로 필터링

날짜 선택기를 사용하여 특정 기간의 로그를 필터링할 수 있습니다:

빠른 프리셋 - 일반적인 시간 범위 선택: 지난 1시간, 3시간, 6시간 또는 12시간
시작 시간 - 범위의 사용자 지정 시작 시간 설정
종료 시간 - 범위의 커스텀 종료 시간 설정
캘린더 - 캘린더 뷰에서 특정 날짜 선택

“Select”를 클릭해 선택한 날짜 범위를 적용하고, “Cancel”을 클릭하면 선택기를 닫습니다.

액션 유형별 필터링

Actions 드롭다운에서 특정 이벤트 유형으로 로그를 필터링할 수 있습니다:

이벤트 유형별로 로그를 필터링하는 Actions 필터 드롭다운 — Actions 필터

사용 가능한 액션 필터는 다음과 같습니다:

디바이스 하트비트 - 디바이스의 주기적 헬스 체크
버전 삭제 요청됨 - 번들 버전이 삭제될 때
기본 버전으로 리셋 - 디바이스가 내장 번들로 되돌아갈 때
버전 설치 성공 - 번들 설치 성공
디바이스에 새 버전 전송됨 - Capgo가 디바이스에 업데이트를 보낼 때
버전 설치 실패 - 번들 설치가 실패할 때

상단 검색창에서 특정 액션 타입을 빠르게 찾을 수 있습니다. 여러 액션을 선택하면 선택한 타입 중 하나라도 일치하는 로그가 표시됩니다.

로그 스니펫 샘플 (가상 데이터)

시간 (UTC)	기기 ID	작업	버전	의미
2025-01-14 10:00:01	`A1B2C3`	`get`	2.4.1	기기가 Capgo에 업데이트가 있는지 확인했습니다
2025-01-14 10:00:03	`A1B2C3`	`download_manifest_start`	2.4.1	Delta 다운로드 시작; SDK에서 변경된 delta 파일을 곧 다운로드합니다
2025-01-14 10:00:07	`A1B2C3`	`download_40`	2.4.1	Bundle 다운로드 40% 완료
2025-01-14 10:00:12	`A1B2C3`	`download_zip_complete`	2.4.1	Zip 다운로드 완료
2025-01-14 10:00:13	`A1B2C3`	`set`	2.4.1	Bundle 설치 완료 및 다음 실행 대상으로 지정됨
2025-01-14 10:05:00	`B9C8D7`	`disableAutoUpdateToMajor`	1.9.0	Channel 정책에 의해 2.x 버전으로의 전환이 차단되었습니다
2025-01-14 10:05:05	`B9C8D7`	`rateLimited`	내장 버전	디바이스가 요청 한도에 도달했습니다. SDK는 재시작 시까지 백오프됩니다

로그 시나리오 예시

로그가 어떤 정보를 제공하는지 이해하도록, 실제 디바이스 업데이트 여정을 보여주는 예시 시퀀스를 소개합니다:

업데이트 성공 흐름

정상적인 업데이트가 로그에 어떻게 표시되는지 확인해 보세요:

시간	기기 ID	작업	버전	의미
10:00:01	`a1b2c3d4`	`get`	1.2.0	디바이스가 업데이트를 확인하고 버전 1.2.0 정보를 받았습니다
10:00:02	`a1b2c3d4`	`download_10`	1.2.0	다운로드 시작, 10% 완료
10:00:03	`a1b2c3d4`	`download_50`	1.2.0	다운로드 50% 진행 중
10:00:05	`a1b2c3d4`	`download_complete`	1.2.0	다운로드가 성공적으로 완료되었습니다
10:00:06	`a1b2c3d4`	`set`	1.2.0	Bundle이 설치되고 활성화되었습니다

기기가 최신 상태입니다

디바이스가 확인했지만 이미 최신 버전을 가지고 있는 경우:

시간	기기 ID	작업	버전	의미
14:30:00	`e5f6g7h8`	`noNew`	1.2.0	기기가 이미 최신 버전입니다. 업데이트가 필요하지 않습니다.

롤백이 발생한 업데이트 실패

업데이트가 실패해 기기가 롤백되면:

시간	기기 ID	작업	버전	의미
11:15:00	`i9j0k1l2`	`get`	1.3.0	기기에서 업데이트 정보 수신 완료
11:15:02	`i9j0k1l2`	`download_complete`	1.3.0	다운로드 완료
11:15:03	`i9j0k1l2`	`set`	1.3.0	Bundle 설정 완료
11:15:10	`i9j0k1l2`	`update_fail`	1.3.0	앱 충돌 또는 `notifyAppReady()` 호출되지 않음 - 롤백 실행
11:15:11	`i9j0k1l2`	`reset`	내장 버전	기기가 내장 버전으로 롤백되었습니다

조치 필요: 앱이 다음을 호출하는지 확인하세요 notifyAppReady() 초기화 성공 후. 참고: 플러그인 문서 에서 확인하세요.

다운로드 실패

네트워크 문제로 다운로드할 수 없을 때:

시간	기기 ID	작업	버전	의미
09:45:00	`m3n4o5p6`	`get`	1.2.0	기기에서 업데이트 정보 수신 완료
09:45:01	`m3n4o5p6`	`download_30`	1.2.0	다운로드가 시작되었지만…
09:45:15	`m3n4o5p6`	`download_fail`	1.2.0	다운로드 실패 (네트워크 타임아웃, 연결 끊김 등)

조치 필요: 다음 앱 실행 시 기기에서 자동으로 재시도합니다. 이 현상이 자주 발생하지 않는 한 별도 조치는 필요하지 않습니다.

플랜 한도 도달

계정의 디바이스 한도에 도달하면:

시간	기기 ID	작업	버전	의미
16:00:00	`q7r8s9t0`	`needPlanUpgrade`	-	플랜을 업그레이드하거나 청구 주기가 리셋될 때까지 이 디바이스는 업데이트를 받지 못합니다

조치 필요: 플랜 업그레이드 또는 다음 청구 주기를 기다리세요.

업데이트를 차단하는 채널 설정

채널 설정으로 업데이트가 차단되는 경우:

시간	기기 ID	작업	버전	의미
12:00:00	`u1v2w3x4`	`disableAutoUpdateToMajor`	2.0.0	v1.x 기기는 v2.x로 자동 업데이트할 수 없음 (메이저 버전 점프 차단)
12:05:00	`y5z6a7b8`	`disableEmulator`	1.2.0	에뮬레이터가 감지됐고 채널이 에뮬레이터를 차단함
12:10:00	`c9d0e1f2`	`disableDevBuild`	1.2.0	개발 빌드가 감지됐고 채널이 개발 빌드를 차단함

조치 필요: 이는 의도된 보호 조치입니다. 이러한 업데이트를 허용하려면 다음을 수정하세요. 채널 설정.

로그 코드 (Capgo 백엔드 enum)

이 코드들은 다음에서 가져온 것입니다. stats_action 대시보드 API에서 사용하는 enumcapgo/src/types/supabase.types.ts). UI에서 새로운 code를 확인했다면, 이는 SDK 또는 백엔드에서 출력되어 이 목록과 검증된 것입니다.

정상 경로 & 라이프사이클

Code	의미
`get`	디바이스가 채널에 연결된 번들을 Capgo에 요청했습니다
`download_manifest_start`, `download_manifest_complete`	델타 다운로드 시작/완료 (델타 파일이 포함된 번들 업로드 시)
`download_zip_start`, `download_zip_complete`	Zip 아카이브 다운로드 시작 / 완료
`download_10` … `download_90`	다운로드 진행 마일스톤
`download_0`	첫 번째 진행 이벤트의 0% 마커
`download_complete`	전체 번들 다운로드 완료
`set`	다음 실행을 위해 번들 스테이징 완료
`reset`	기기가 내장 번들로 되돌아감
`delete`	로컬 스토리지에서 번들 제거됨
`uninstall`	앱 제거 감지됨
`app_moved_to_foreground`, `app_moved_to_background`	SDK에서 기록한 앱 라이프사이클 이벤트
`ping`	기기 헬스체크/하트비트 확인
`setChannel`, `getChannel`	SDK 호출로 채널을 오버라이드하거나 가져옴

새 정책 차단/스로틀링 빠른 수정

Code	발생 원인	해결 방법
`invalidIp`	Capgo에서 봇으로 의심되는 트래픽(Google/cloud 인프라 IP)을 감지했습니다.	실제 사용자의 경우 무시해도 됩니다. 실제 기기와 일반 네트워크에서 다시 시도하거나 잠시 후 확인하세요.
`needPlanUpgrade`	조직의 플랜 또는 기기 제한에 도달했습니다.	대시보드에서 플랜을 업그레이드하거나 다음 결제 주기까지 기다려 주세요.
`semver_error`	config에 있는 Native app 버전이 누락되었거나 유효한 semver가 아닙니다 (`x.y.z`).	설정 `plugins.CapacitorUpdater.version` 유효한 semver로 수정한 다음, 해당 항목을 확인하세요 SemVer 테스터 그리고 앱을 다시 빌드하세요.
`disablePlatformIos`	채널 정책에서 iOS가 비활성화되어 있습니다.	실수로 설정한 것이라면 해당 채널에서 iOS를 활성화하고 라우팅을 다시 게시하세요. 이 트랙에서 의도적으로 iOS를 차단하려는 것이라면 비활성 상태로 두고 iOS 빌드를 별도 채널로 옮기세요.
`disablePlatformAndroid`	채널 정책에서 Android가 비활성화되어 있습니다.	실수로 설정한 것이라면 해당 채널에서 Android를 활성화하고 라우팅을 다시 게시하세요. 이 트랙에서 의도적으로 Android를 차단하려는 것이라면 비활성 상태로 두고 Android 빌드를 별도 채널로 옮기세요.
`disableAutoUpdate`	채널의 자동 업데이트 모드가 이 업데이트 방식을 차단합니다.	의도한 롤아웃을 허용하려면 채널 자동 업데이트 정책(major/minor/patch/metadata/none)을 변경하세요.
`disableAutoUpdateUnderNative`	채널이 디바이스 baseline보다 오래된 업데이트를 차단하도록 설정되어 있습니다.	native baseline과 같거나 높은 버전을 푸시하거나, 해당 under-native 보호 기능을 비활성화하세요.
`disableAutoUpdateMetadata`	채널 요구 사항: `min_update_version` metadata 및 앱 버전이 더 낮습니다.	설정 `min_update_version` 대상 bundle 또는 더 최신 native 버전의 릴리스용입니다.
`disableAutoUpdateToMajor`	채널이 메이저 버전 점프를 차단합니다.	메이저 버전을 동일한 채널 전략에 유지하거나, 이 트랙에서 메이저 점프를 허용하세요.
`disableAutoUpdateToMinor`	채널이 마이너 버전 점프를 차단합니다.	마이너 버전을 동일한 채널 전략에 유지하거나, 이 트랙에서 마이너 점프를 허용하세요.
`disableAutoUpdateToPatch`	이 플로우에서는 채널이 패치 레벨 점프를 차단합니다.	릴리스 주기를 맞추거나, 이 트랙의 채널 정책에서 패치 점프를 허용하세요.
`disableEmulator`	이 채널에서는 에뮬레이터 업데이트가 허용되지 않습니다.	실수였다면 에뮬레이터를 검증하는 테스트 채널에서 에뮬레이터 업데이트를 켜세요. 의도한 것이라면 이 채널은 에뮬레이터 차단 상태로 두고, 에뮬레이터 빌드는 다른 채널을 사용하세요.
`disableDevBuild`	이 채널에서는 Dev 빌드가 차단됩니다.	실수였다면 Dev 업데이트를 허용하거나 이 기기를 Dev가 활성화된 채널로 옮기세요. 의도한 것이라면 이 채널은 릴리스 빌드 전용으로 잠가 두세요.
`disableProdBuild`	프로덕션 모드에서 기기 빌드가 호출되었습니다 `/updates`, 채널이 이를 차단했습니다.	실수로 발생한 경우 해당 채널에서 프로덕션 업데이트를 허용하고 다시 게시하세요. 의도한 경우라면 제한을 유지하고 프로덕션 빌드를 올바른 채널/빌드로 보내세요.
`cannotGetBundle`	Capgo가 선택된 번들에 대해 유효한 다운로드 URL을 생성하지 못했습니다.	번들을 다시 업로드하세요( `--delta` 델타 파일이 필요한 경우) R2/공개 번들 설정도 확인하세요.
`cannotUpdateViaPrivateChannel`	앱이 셀프 할당이 허용되지 않는 비공개 채널로 자체 전환을 시도했습니다.	활성화 `allow_device_self_set` 채널에서 설정하거나 공개/허용된 채널로 전환하세요.
`channelMisconfigured`	채널 자동 업데이트 규칙에 필요한 데이터가 없습니다(`version_number` 없이 `min_update_version`).	해당 규칙의 누락된 설정을 채우거나 더 간단한 자동 업데이트 모드로 전환하세요.
`missingBundle`	번들에 다운로드 가능한 페이로드가 없습니다( `external_url`/`r2_path` 델타 파일도 없음).	버전을 다시 빌드/업로드하고 bundle에 실제 파일 내용이 있는지 확인하세요.
`NoChannelOrOverride`	이 기기와 일치하는 channel이 없습니다 (cloud default 없음 + config fallback 없음 + override 없음).	dashboard에서 channel default를 설정하거나 test를 유지하세요 `defaultChannel` 해당 build에.
`rateLimited`	짧은 시간 내에 update/channel 호출이 너무 많습니다 (흔히 render-loop에서 발생) `setChannel`/`getChannel`).	render에서 호출을 중단하세요. 사용자 액션 시에만 호출하세요. 다음을 사용하세요 `defaultChannel` 에서 `capacitor.config`.
`keyMismatch`	앱과 bundle 암호화 키 ID가 다릅니다 (`device_key_id` vs `bundle_key_id`).	콘솔에서 기기와 bundle 키 ID를 비교하세요. 다르면 동일한 키와 일치하는 CLI/플러그인 버전으로 게시하세요. 버전 간 키 인코딩이 다를 수 있습니다.
`disableDevice`	이 channel이 실제 기기 차단으로 설정되어 있어 실제 스마트폰/태블릿이 차단되었습니다.	실수로 차단된 경우 해당 채널에서 실기기 업데이트를 활성화하세요. 의도적으로 차단한 경우 차단 상태를 유지하고 실기기를 다른 채널로 라우팅하세요.
`disablePlatformElectron`	이 채널에서는 Electron이 차단되었습니다.	실수로 차단된 경우, 이 채널에서 Electron을 활성화하고 라우팅을 다시 게시하세요. 의도된 설정이라면 차단을 유지하고 Electron 사용자를 전용 채널로 안내하세요.
`customIdBlocked`	커스텀 device ID가 전송되었지만, 이 앱은 커스텀 ID를 허용하지 않습니다.	커스텀 ID 전송을 끄거나, 워크플로우에 꼭 필요한 경우에만 커스텀 ID를 활성화하세요.
`blocked_by_server_url`	앱에 `server.url` 설정되어 있어, Capacitor이 로컬 파일 대신 원격 URL을 서빙합니다.	제거/지우기 `server.url` 프로덕션 빌드용으로 업데이트 페이로드를 로컬로 유지하세요.
`backend_refusal`	업데이터가 `v4`이며, 백엔드에서 더 이상 허용하지 않습니다.	plugin/CLI을(를) 다음 버전으로 업그레이드하세요: `v5`+ (권장 `v8`), Capacitor 포함 `v5`+, 그런 다음 번들 메타데이터를 다시 빌드하고 재배포합니다.
설정 또는 정책 차단

Code	업데이트가 차단된 이유
`disableAutoUpdate`, `disableAutoUpdateToMajor`, `disableAutoUpdateToMinor`, `disableAutoUpdateToPatch`, `disableAutoUpdateMetadata`, `disableAutoUpdateUnderNative`	채널 전략이 이를 허용하지 않음 semver 점프
`disablePlatformIos`, `disablePlatformAndroid`	채널에서 플랫폼이 비활성화됨
`disableDevBuild`, `disableEmulator`	개발 빌드 또는 에뮬레이터 허용 안 됨
`disableProdBuild`, `disableDevice`, `disablePlatformElectron`	이 채널에서는 프로덕션 빌드, 실제 기기 또는 Electron이 차단됩니다.
`customIdBlocked`	이 앱에서는 사용자 지정 기기 ID가 허용되지 않습니다.
`cannotUpdateViaPrivateChannel`, `NoChannelOrOverride`, `channelMisconfigured`	채널 선택 또는 오버라이드 실패
`missingBundle`, `cannotGetBundle`	채널이 Capgo에서 서빙할 수 없는 번들을 가리킴
`needPlanUpgrade`	조직이 플랜/기기 한도에 도달함

다운로드 / 무결성 / 설치 실패

Code	의미
`download_fail`	번들 다운로드 실패 (네트워크 또는 응답 오류)
`download_manifest_file_fail`, `download_manifest_checksum_fail`, `download_manifest_brotli_fail`	델타 파일을 가져오거나 검증할 수 없음
`checksum_fail`, `checksum_required`	무결성 검사 실패 또는 체크섬 누락
`unzip_fail`, `directory_path_fail`, `canonical_path_fail`, `windows_path_fail`	파일 시스템 또는 압축 해제 검증 실패
`decrypt_fail`	복호화 실패 (암호화 번들)
`update_fail`	번들이 설치되었지만 앱이 호출하지 않음 `notifyAppReady()`; 롤백 트리거됨
`download_zip_*` 이후 없음 `set`	다운로드가 완료되었지만 설치 단계가 완료되지 않음

런타임 / 플랫폼 이벤트

Code	의미
`app_crash`, `app_crash_native`	JavaScript 또는 네이티브 런타임 계층의 크래시 이벤트. 메타데이터에는 스택, 소스, 활성 버전 정보가 포함되는 경우가 많습니다.
`app_anr`	Android에서 Application Not Responding을 보고했습니다.
`app_killed_low_memory`, `app_killed_excessive_resource_usage`	메모리 또는 리소스 한계로 인한 앱 프로세스 종료.
`app_initialization_failure`, `app_memory_warning`	정상적인 런타임 전에 시작이 중단되었거나 메모리 압력이 관찰되었습니다.
`webview_javascript_error`, `webview_unhandled_rejection`, `webview_resource_error`, `webview_security_policy_violation`, `webview_unclean_restart`, `webview_render_process_gone`, `webview_content_process_terminated`	WebView 라이프사이클 및 JS/렌더링 오류. 스택 트레이스, 세션/디바이스 컨텍스트, URL/상태를 캡처하여 빠른 수정을 위해 JS 및 네이티브 계층 모두에 Sentry를 설치하세요.
`os_version_changed`, `native_app_version_changed`	OS 또는 네이티브 앱 버전이 변경됨. 이는 플랫폼 레벨 롤아웃 효과를 웹 번들 동작과 구분하는 데 도움이 됩니다.

➡️ code별 더 자세한 안내가 필요하세요? 다음을 확인하세요: 전체 로그 Code 레퍼런스 및 디버깅 가이드.

로그 상세 정보 확인하기

특정 로그 항목을 클릭하면 일반적으로 다음으로 이동합니다: 해당 디바이스 페이지. 이를 통해 해당 디바이스의 전체 히스토리를 확인할 수 있으며, 디바이스별 이슈를 진단하거나 업데이트 과정을 파악하는 데 매우 유용합니다.

로그에서 계속하기

사용 중이라면 로그 대시보드 및 API 운영을 계획하려면, 이를 다음과 연결하세요 API 개요 구현 세부 사항은 API 개요에서 소개 구현 세부 사항은 소개에서 API 키 구현 세부 사항은 API 키에서 기기 구현 세부 사항은 기기에서, 그리고 번들 Bundles의 구현 세부 사항은