델타 업데이트

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

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

이는 다운로드 데이터 양을 최소화하므로, 네트워크 속도가 느리거나 데이터 사용량이 제한적인 환경의 사용자에게 특히 유용합니다.

두 번째 장점은 이미지나 비디오처럼 변경이 거의 없는 대용량 에셋이 있는 경우입니다. 압축된 JS 파일과 달리 이러한 에셋은 한 번만 다운로드하면 됩니다.

Delta 업데이트 작동 방식

Capgo의 Delta 업데이트는 앱에 설치된 Capgo 플러그인이 처리합니다. 앱의 새 버전을 업로드할 때 --delta flag를 사용하면 Capgo는 다음을 수행합니다:

빌드에 포함된 각 파일은 delta 파일로 개별 업로드됩니다
각 delta 파일의 checksum을 생성합니다
경로와 checksum이 포함된 delta 파일 목록을 Capgo 데이터베이스에 저장합니다

앱을 실행 중인 기기가 업데이트를 확인하면, Capgo 플러그인이 새 bundle에 대한 delta 파일 목록을 받습니다. 플러그인은 이를 이미 가지고 있는 파일과 비교하고, checksum과 파일 경로를 기반으로 변경된 파일을 식별합니다.

그런 다음 플러그인은 전체 JS bundle 대신 변경된 파일만 다운로드합니다. 다운로드한 파일을 이미 가지고 있던 변경되지 않은 파일과 결합해 앱의 새 버전을 재구성합니다.

어떤 기기가 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 업데이트를 자동으로 전송하고, 대화형 환경에서는 업로드 전 확인 프롬프트를 표시합니다. 기존 directUpdate 설정도 여전히 감지됩니다. 전체 번들을 강제로 업로드하려면 --no-delta 를 사용하세요.

Delta update 제한 사항

빈 파일: CLI 로그는 Ignoring empty file... 또한 delta 파일에서 0바이트 파일을 제외합니다. 업로드가 실패하는 것은 아니므로, 빈 파일을 추가하면 배포를 중단하지는 않지만 결과 번들이 달라질 수 있습니다. Delta bundle 경로에 0바이트 파일을 포함하지 마세요.
경로 내 공백: bundle 경로에 공백이 있으면 파일을 업로드하기 전에 Delta 업로드가 실패합니다. Delta update를 업로드하기 전에 파일이나 디렉토리 이름을 바꿔 공백을 제거하세요.

Delta update 강제 적용

모든 업로드가 Delta update가 되도록 하고 실수로 전체 번들이 업로드되는 것을 막으려면 다음 --delta-only 플래그를 사용하세요:

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

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

다음 기능을 사용할 수도 있습니다 --delta-only if:

항상 Delta 업데이트만 사용하고 전체 bundle 업로드는 절대 허용하지 않으려는 경우
CI/CD pipeline을 설정 중이고 모든 자동 업로드가 Delta로 이루어지게 하려는 경우
앱 용량이 크고 대역폭이 제한적이라 업로드/다운로드 크기를 최소화해야 하는 경우

If you need to do a full bundle upload while --delta-only 설정되어 있다면, 단순히 다음 없이 upload 명령어를 실행하세요 --delta-only. 이렇게 하면 해당 업로드에 대해서만 설정이 재정의되어, 필요할 때 전체 bundle을 푸시할 수 있습니다.

문제 해결

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

You’re using the --delta 새 버전을 업로드할 때마다 사용하고 있는지
사용 중이라면 --delta-only, 실수로 다음을 빠뜨리지 않았는지 확인하세요: --delta 플래그
기기에서 Delta를 지원하는 플러그인 버전을 실행 중입니다 (5.10.0+, 6.25.0+, 7.0.35+, 또는 8+)
채널 다운로드 형식이 일치하지 않습니다. Full zip만 가능
기기가 안정적인 네트워크에 연결되어 있고 Capgo 서버에 접속할 수 있습니다.

Capgo webapp에서 마지막 upload의 상세 정보를 확인할 수도 있습니다:

다음으로 이동하세요: 웹앱
앱을 클릭하세요
통계 바에서 번들 숫자를 클릭하세요.
마지막 번들을 선택합니다.
다음 Delta files 행을 확인하세요. 여기에는 델타 파일 없음 라고 표시되며, 이는 번들이 전체 zip 파일로만 업로드되었음을 의미합니다.

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

이제 완료되었습니다! 이 --delta 플래그는 Capgo가 Delta 업데이트에 필요한 개별 delta 파일들을 업로드하도록 지시합니다.

참고로, Delta 업데이트 방식으로 배포하려는 새 버전을 업로드할 때마다 --delta 를 사용해야 합니다. 플래그를 누락하면 Capgo는 전체 JS 번들을 단일 파일로 업로드하며, 아주 작은 부분만 변경되었더라도 디바이스는 번들 전체를 다운로드하게 됩니다.

Delta update 이후 계속하기

사용 중이라면 델타 업데이트 live update 배포를 계획하려면, 다음과 연결하세요 Capgo Live Updates Capgo Live Updates의 제품 워크플로우를 보려면, 개요 Overview의 구현 상세를 보려면, 기능 Features의 구현 상세를 보려면, 업데이트 동작 Update Behavior의 구현 세부 사항은 다음과 같고, 업데이트 유형 Update Types의 구현 세부 사항은 다음과 같습니다.