Capgo Delta Updates: --delta 옵션으로 변경된 파일만 배포하세요

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

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 updates를 사용하면 Capgo 대역폭 사용량도 줄여줍니다. 대역폭은 기기가 실제로 다운로드한 파일만 집계하므로, Delta를 사용하면 전체 bundle이 아니라 변경된 파일만 집계됩니다. edge에 이미 캐시된 파일이나 전체 zip은 집계되지 않으며, 중단된 다운로드는 이미 다운로드된 부분을 두 번 집계하지 않고 중단된 지점부터 재개됩니다. 자세한 내용은 다음을 참조하세요: 대역폭은 어떻게 계산되나요?.

Delta 업데이트 활성화하기

Capgo 앱에서 Delta updates를 활성화하려면 간단히 다음을 사용하세요: --delta 새 버전을 업로드할 때 사용하는 플래그:

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

만약 autoUpdate 즉시 적용 모드로 설정되어 있으면 ("atInstall", "onLaunch", 또는 "always") capacitor.configCLI가 이를 감지합니다. 비대화형 환경에서는 Delta 업데이트를 자동으로 전송하고, 대화형 환경에서는 업로드 전에 확인 프롬프트를 표시합니다. 기존 directUpdate config도 여전히 감지됩니다. --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로 이루어지게 하려는 경우
앱 용량이 크고 대역폭이 제한적이라 업로드/다운로드 크기를 최소화해야 하는 경우

전체 bundle 업로드가 필요하지만 --delta-only 이 설정되어 있을 때, 업로드 명령을 실행할 때 --delta-only. 이렇게 하면 해당 업로드에 대해서만 설정이 재정의되어, 필요할 때 전체 bundle을 푸시할 수 있습니다.

문제 해결

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

다음 기능을 사용 중입니다: --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 플래그는 Capgo에 Delta 업데이트에 필요한 개별 델타 파일을 업로드하도록 지시합니다.

다음과 같이 사용해야 합니다 --delta Delta 업데이트로 전달하려는 새 버전을 업로드할 때마다 이 플래그를 사용하세요. 플래그를 생략하면 Capgo는 전체 JS 번들을 단일 파일로 업로드하며, 변경된 부분이 적더라도 기기는 전체 번들을 다운로드합니다.

Delta update 이후 계속하기

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