로그

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

로그 페이지는 애플리케이션의 업데이트 이벤트와 진단 정보의 상세 기록을 제공합니다. 이는 업데이트 프로세스 모니터링, 문제 해결, 디바이스가 Capgo와 어떻게 상호작용하는지 이해하는 데 중요합니다. 앱을 클릭한 다음 “로그” 탭을 클릭(일부 이전 스크린샷이나 문서에서는 “업데이트”라고 불렸음)하여 접근할 수 있습니다.

거기서 로그 항목 목록을 보여주는 다음과 같은 페이지가 표시됩니다:

로그 페이지 개요

로그 페이지 인터페이스에는 다음이 포함됩니다:

1. 로그 탭 - 로그 뷰에 접근하기 위한 내비게이션 탭
2. 새로고침 버튼 - 최신 데이터로 로그 목록 새로고침
3. 시간 범위 & 작업 필터 - 날짜 범위와 작업 유형으로 로그 필터링 (아래 섹션 참조)

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

• 타임스탬프 (UTC)
• 디바이스 ID
• 작업 코드 (무슨 일이 일어났는지)
• 버전 이름 (번들 또는 builtin)

행을 클릭하면 전체 기록이 있는 디바이스 상세 페이지로 이동합니다.

날짜 범위로 필터링

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

날짜 범위 필터

1. 빠른 프리셋 - 일반적인 시간 범위 선택: 최근 1시간, 3시간, 6시간 또는 12시간
2. 시작 시간 - 범위의 사용자 정의 시작 시간 설정
3. 종료 시간 - 범위의 사용자 정의 종료 시간 설정
4. 캘린더 - 캘린더 뷰를 사용하여 특정 날짜 선택

“선택”을 클릭하여 선택한 날짜 범위를 적용하거나, “취소”를 클릭하여 선택기를 닫습니다.

작업 유형으로 필터링

작업 드롭다운을 사용하면 특정 이벤트 유형으로 로그를 필터링할 수 있습니다:

작업 필터

사용 가능한 작업 필터에는 다음이 포함됩니다:

• 디바이스 하트비트 - 디바이스의 주기적인 상태 확인
• 버전 삭제 요청됨 - 번들 버전이 삭제될 때
• 기본 버전으로 재설정 - 디바이스가 내장 번들로 되돌아갈 때
• 버전 설치 성공 - 번들 설치 성공
• 새 버전이 디바이스로 전송됨 - 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	매니페스트 다운로드 시작; SDK가 파일 다운로드 준비 중
2025-01-14 10:00:07	A1B2C3	download_40	2.4.1	번들 다운로드 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	번들이 설치되고 다음 실행을 위해 표시됨
2025-01-14 10:05:00	B9C8D7	disableAutoUpdateToMajor	1.9.0	채널 정책이 2.x로의 점프를 차단함
2025-01-14 10:05:05	B9C8D7	rateLimited	builtin	디바이스가 요청 제한에 도달; 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	번들이 설치되고 활성화됨

디바이스가 이미 최신 상태

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

시간	디바이스 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	번들이 설정됨
11:15:10	i9j0k1l2	update_fail	1.3.0	앱이 충돌하거나 notifyAppReady()가 호출되지 않음 - 롤백 실행
11:15:11	i9j0k1l2	reset	builtin	디바이스가 내장 버전으로 되돌아감

필요한 작업: 앱이 성공적인 초기화 후 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)

이 코드들은 대시보드 API에서 사용하는 stats_action enum에서 가져옵니다 (capgo/src/types/supabase.types.ts). UI에서 새 코드를 보면 SDK 또는 백엔드에서 발행되어 이 목록에 대해 검증되었습니다.

해피 패스 & 라이프사이클

코드	의미
get	디바이스가 Capgo에 현재 채널 매니페스트 요청
download_manifest_start, download_manifest_complete	매니페스트 다운로드 시작/완료 (델타 또는 멀티파일 번들용)
download_zip_start, download_zip_complete	zip 아카이브 다운로드 시작/완료
download_10 … download_90	다운로드 진행률 마일스톤
download_complete	전체 번들 다운로드됨
set	번들이 다음 실행을 위해 스테이징됨
reset	디바이스가 내장 번들로 되돌아감
delete	번들이 로컬 저장소에서 삭제됨
uninstall	앱 제거 감지됨
app_moved_to_foreground, app_moved_to_background	SDK에서 기록한 앱 라이프사이클 이벤트
ping	디바이스의 상태/하트비트 확인
setChannel, getChannel	SDK 호출을 통해 채널 오버라이드 또는 가져옴

설정 또는 정책 차단

코드	업데이트가 차단된 이유
disableAutoUpdate, disableAutoUpdateToMajor, disableAutoUpdateToMinor, disableAutoUpdateToPatch, disableAutoUpdateMetadata, disableAutoUpdateUnderNative	채널 전략이 이 semver 점프를 금지
disablePlatformIos, disablePlatformAndroid	채널에서 플랫폼이 비활성화됨
disableDevBuild, disableEmulator	개발 빌드 또는 에뮬레이터가 허용되지 않음
cannotUpdateViaPrivateChannel, NoChannelOrOverride, channelMisconfigured	채널 선택 또는 오버라이드 실패
missingBundle, cannotGetBundle	매니페스트가 Capgo가 제공할 수 없는 번들을 참조함
needPlanUpgrade	조직이 플랜/디바이스 한도에 도달
rateLimited	요청이 너무 많음; SDK가 재시작까지 제한
blocked_by_server_url, backend_refusal, InvalidIp	서버 측 규칙이 요청을 차단

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

코드	의미
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()를 호출하지 않음; 롤백 실행
이후 set 없는 download_zip_*	다운로드는 완료되었지만 설치 단계가 완료되지 않음

➡️ 코드별 더 자세한 안내가 필요하신가요? **전체 로그 코드 참조 및 디버깅 가이드**를 참조하세요.

로그에 대한 자세한 정보 얻기

특정 로그 항목을 클릭하면 일반적으로 디바이스 페이지로 이동합니다. 이를 통해 해당 특정 디바이스의 전체 기록을 볼 수 있으며, 디바이스별 문제를 진단하거나 업데이트 여정을 이해하는 데 매우 유용합니다.