Delta 업데이트

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

Capgo의 Live Update 시스템은 전체 JS bundle을 보내는 대신 변경된 파일만 전송해 더 빠르고 효율적으로 업데이트를 제공합니다.

이 방식은 다운로드해야 하는 데이터 양을 최소화하므로, 네트워크가 느리거나 데이터 사용량이 제한된 사용자에게 특히 유용합니다.

두 번째 장점은 이미지나 비디오처럼 자주 바뀌지 않는 대용량 에셋이 있는 경우입니다. 압축된 JS 파일과 달리 이런 에셋은 한 번만 다운로드됩니다.

Delta Updates 작동 원리

Capgo의 Delta updates는 앱에 설치된 Capgo 플러그인이 처리합니다. 다음 명령어로 앱의 새 버전을 업로드하면, --delta flag를 사용하면 Capgo는 다음 작업을 수행합니다:

빌드된 각 파일은 델타 파일 형태로 개별적으로 upload됩니다.
각 델타 파일에 대해 체크섬이 생성됩니다.
경로와 체크섬이 포함된 델타 파일 목록은 Capgo 데이터베이스에 저장됩니다.

앱이 실행 중인 기기에서 업데이트를 확인하면, Capgo 플러그인이 새 번들의 델타 파일 목록을 받습니다. 플러그인은 체크섬과 파일 경로를 기반으로 기존 파일과 비교하여 변경된 파일을 식별합니다.

그 다음 플러그인은 전체 JS 번들을 받는 대신 변경된 파일만 download합니다. 다운로드한 파일과 기존의 변경되지 않은 파일을 결합하여 앱의 새 버전을 재구성합니다.

어떤 기기가 Delta를 받고 어떤 기기가 전체 zip을 받나요?

다음 방식으로 업로드된 번들은 --delta 전체 zip 파일과 delta 파일을 모두 가집니다. 기본 설정인 Zip + delta 다운로드 형식을 사용하는 채널에서는 각 기기가 지원 가능한 최적의 패키지를 받습니다:

Delta를 지원하는 플러그인 버전을 사용하는 기기는 (5.10.0+, 6.25.0+, 7.0.35+, 또는 8+) 변경된 delta 파일만 다운로드합니다.
Delta를 지원하지 않는 이전 플러그인 버전의 기기는 전체 zip을 다운로드합니다.
다음 방식 없이 업로드된 번들은 --delta delta 파일이 없으므로 모든 기기가 전체 zip을 다운로드합니다.

Delta를 활성화하더라도 여전히 전체 zip 다운로드가 발생할 수 있습니다. 이는 이전 plugin 버전이 포함된 구형 Native Build를 사용하는 기기에서 발생하는 현상이며, 사용자가 스토어에서 앱을 업데이트하면 해결됩니다.

채널별로 다음 설정을 통해 변경할 수 있습니다: 다운로드 형식 설정.

Delta 업데이트 및 대역폭 사용량

Delta 업데이트를 사용하면 Capgo 대역폭 사용량도 줄어듭니다. 대역폭은 기기가 실제로 다운로드한 파일만 계산하므로, Delta를 사용하면 전체 bundle이 아닌 변경된 파일만 계산됩니다. Edge에 이미 캐싱된 파일이나 전체 zip은 계산에서 제외되며, 중단된 다운로드는 중단된 지점부터 재개되어 이미 다운로드한 부분을 중복 계산하지 않습니다. 자세한 내용은 대역폭은 어떻게 계산되나요?.

Delta Updates 활성화하기

Capgo 앱에 Delta 업데이트를 활성화하려면, 새 버전을 업로드할 때 다음 --delta 플래그를 사용하세요:

npx @capgo/cli@latest bundle upload --delta

만약 autoUpdate 가 즉시 적용 모드로 설정되어 있으면 ("atInstall", "onLaunch", 또는 "always") 이 capacitor.config에서 CLI 가 이를 감지합니다. 비대화형 환경에서는 Delta 업데이트를 자동으로 전송하며, 대화형 환경에서는 업로드 전 확인 prompt를 표시합니다. 기존 directUpdate 설정도 여전히 감지됩니다. 전체 bundle 업로드를 강제하려면 --no-delta 를 사용하세요.

Delta 업데이트 제한 사항

빈 파일: CLI 로그 Ignoring empty file... 또한 delta 파일에서 0바이트 파일을 제외합니다. 업로드가 실패하지 않으므로, 빈 파일을 추가해도 배포를 중단하지 않고 결과 번들을 변경할 수 있습니다. Delta bundle 경로에 0바이트 파일을 포함하지 마세요.
경로 내 공백: 번들 경로에 공백이 포함되어 있으면 파일 업로드 전 Delta 업로드가 실패합니다. Delta update를 업로드하기 전에 파일이나 디렉토리의 이름을 변경하여 공백을 제거하세요.

Delta Updates 강제 적용

모든 업로드가 Delta update로만 이루어지도록 보장하고 실수로 전체 번들이 업로드되는 것을 방지하려면, --delta-only 플래그:

npx @capgo/cli@latest bundle upload --delta-only

호출 시 --delta-only 를 사용하면 Capgo은 전체 zip 파일 없이 delta 파일만 업로드합니다. Delta를 지원하지 않는 플러그인 버전을 사용하는 기기는 업데이트를 다운로드할 수 없습니다.

다음 기능을 사용하고 싶을 수 있습니다: --delta-only if:

항상 Delta 업데이트를 사용하고 전체 bundle upload는 절대 허용하고 싶지 않을 때
CI/CD pipeline을 설정 중이고 모든 자동 upload가 Delta로 이루어지도록 하고 싶을 때
앱 용량이 크고 대역폭이 제한적이라 upload/download 크기를 최소화해야 할 때

If you need to do a full bundle upload while --delta-only 설정되어 있다면, 단순히 upload 명령어를 실행하세요. --delta-only이렇게 하면 해당 upload에 한해 설정이 덮어써져, 필요할 때 전체 bundle을 푸시할 수 있습니다.

문제 해결

Delta 업데이트가 제대로 작동하지 않는 것 같다면 (예: 작은 변경사항에도 기기가 항상 전체 JS bundle을 download하는 경우), 다음을 다시 확인하세요:

현재 사용 중인 --delta flag를 사용하고 있는지
사용 시 --delta-only, 실수로 다음 항목을 누락하지 않았는지 확인하세요: --delta flag
현재 기기에서 Delta를 지원하는 플러그인 버전이 실행 중입니다 (5.10.0+, 6.25.0+, 7.0.35+, 또는 8+)
채널 다운로드 형식이 ...이 아닙니다 Full zip 전용
기기의 네트워크 연결이 안정적이며 Capgo 서버에 접속할 수 있습니다

Capgo webapp을 사용하여 마지막 upload 상세 정보를 확인할 수도 있습니다:

다음으로 이동하세요: webapp
앱을 클릭하세요
통계 바에서 bundles 숫자를 클릭하세요.
마지막 bundle을 선택하세요
해당 행을 확인하세요. Delta files 다음 내용이 표시됩니다. Delta 파일 없음 번들이 전체 zip 파일로만 업로드되었을 때입니다.

문제가 지속되면 Capgo 지원팀에 문의하여 도움을 받으세요. 지원팀에서 서버 logs를 확인하여 Delta 업로드가 정상적으로 처리되고 있는지, 디바이스가 delta 파일을 잘 받고 있는지 확인할 수 있습니다.

이제 끝났습니다! --delta 플래그를 설정하면 Capgo가 Delta update에 필요한 개별 delta 파일들을 업로드합니다.

다음 사항에 유의하세요: --delta Delta update로 배포하려는 새 버전을 업로드할 때마다 매번 사용해야 합니다. 이 플래그를 생략하면 Capgo는 전체 JS bundle을 단일 파일로 업로드하며, 아주 작은 부분만 변경되었더라도 디바이스는 전체 bundle을 다운로드하게 됩니다.

Delta 업데이트로 끊김 없이 이어가세요

사용 중인 경우 Delta 업데이트 live update 배포를 계획하려면, 이를 다음 항목과 연결하세요: Capgo Live Updates Capgo Live Updates의 제품 워크플로우를 위해, 개요 Overview의 구현 세부 사항을 위해, 주요 기능 Features의 구현 세부 사항은, 업데이트 동작 Update Behavior의 구현 세부 사항은, 업데이트 유형 Update Types의 구현 세부 사항을 참조하세요.