롤백

Capgo의 라이브 업데이트를 사용하면 사용자에게 개선 사항과 수정 사항을 빠르게 전달할 수 있지만, 앱을 이전 버전으로 롤백해야 하는 상황도 있습니다. 새 업데이트에서 예상치 못한 심각한 문제가 발생했거나, 수정 작업을 하는 동안 특정 변경 사항을 되돌리고 싶을 때가 그렇습니다.

Capgo는 수동 롤백 옵션과 자동 안전 메커니즘을 모두 포함해 채널의 빌드를 관리하고 사용자가 받는 앱 버전을 제어하는 여러 방법을 제공합니다.

자동 롤백 보호

Capgo에는 문제가 있는 업데이트로부터 사용자를 보호하는 내장 안전 메커니즘이 있습니다. 만약 JavaScript 에러가 notifyAppReady() 메서드가 호출되기 전에 발생하면, 플러그인은 이전의 정상 작동 버전으로 자동으로 롤백합니다.

자동 롤백 작동 방식

새로운 업데이트가 다운로드되어 적용되면, Capgo는 앱이 설정 가능한 시간 내에 메서드를 호출해 notifyAppReady() 업데이트가 성공적으로 로드되었음을 확인하기를 기대합니다. 이 메서드는 다음을 나타냅니다:

• JavaScript 번들이 치명적인 오류 없이 로드됨
• 앱의 핵심 기능이 정상 작동 중입니다
• 해당 업데이트를 유지해도 안전합니다

만약 notifyAppReady() JavaScript 충돌이나 심각한 오류로 인해 호출되지 않을 경우, Capgo은(는) 다음과 같이 동작합니다:

1. 업데이트가 제대로 초기화되지 않았음을 감지합니다
2. 이전의 정상 작동하던 번들로 자동 롤백합니다
3. 문제가 된 업데이트를 실패로 표시하여 재적용을 방지합니다

팁

반드시 다음을 호출해야 합니다 notifyAppReady() 핵심 컴포넌트가 성공적으로 로드된 후, 앱 초기화 단계에서 code을(를) 호출하세요. 그래야 자동 롤백 보호 기능이 의도대로 작동합니다.

import { CapacitorUpdater } from '@capgo/capacitor-updater'

// Call this after your app has successfully initialized
await CapacitorUpdater.notifyAppReady()

이 자동 보호 기능은 실수로 잘못된 업데이트를 배포하더라도 사용자가 작동하지 않는 앱을 사용하게 되는 상황을 방지합니다.

Timeout 설정하기

Capgo가 대기하는 시간을 notifyAppReady() 설정하려면 다음 항목을 appReadyTimeout Capacitor 설정의 다음 항목에 지정하세요:

{
  "plugins": {
    "CapacitorUpdater": {
      "appReadyTimeout": 10000
    }
  }
}

이 appReadyTimeout 값은 밀리초(ms) 단위로 지정합니다. 기본 timeout은 보통 10초이지만, 앱의 초기화 요구 사항에 따라 조정할 수 있습니다. 복잡한 초기화 과정으로 인해 앱 로딩 시간이 길어지는 경우 이 값을 늘리는 것이 좋습니다.

이전 Bundle로 롤백하기

새 빌드를 upload하고 채널에 할당할 때마다 Capgo는 해당 빌드 이력을 보관합니다. 특정 업데이트를 되돌려야 하는 경우, 이전 빌드 중 하나를 선택하여 채널에 다시 배포할 수 있습니다.

가장 기본적인 롤백 방법은 롤백 인터페이스를 사용하는 것입니다. Capgo Dashboard에서 채널을 확인할 때 4번째 탭(History)에 위치해 있습니다. 이 탭에서는 해당 채널에서 사용 가능한 모든 빌드를 한눈에 확인할 수 있어, 이전 버전 중 원하는 버전을 쉽게 선택해 되돌릴 수 있습니다.

History 탭으로 롤백하는 방법:

1. 다음으로 로그인하세요: Capgo 대시보드.

2. “Channels” 섹션으로 이동합니다.

3. 롤백하려는 채널의 이름을 클릭합니다.

4. 채널 뷰의 4번째 탭(History)으로 이동합니다.

5. 빌드 히스토리에서 되돌릴 빌드를 찾습니다.

6. 해당 빌드를 선택해 채널의 활성 빌드로 설정합니다.

7. 해당 빌드로 롤백할 것인지 확인합니다.

다른 방법: Crown 아이콘 사용하기

두 번째 방법으로, 채널의 빌드 히스토리에 있는 각 빌드 옆의 왕관 아이콘을 클릭하여 첫 번째 탭에서 직접 롤백할 수도 있습니다:

1. 채널 뷰의 첫 번째 탭에서 되돌리려는 빌드를 찾으세요.
2. 해당 빌드 옆의 왕관 아이콘을 클릭하면 해당 빌드가 채널의 활성 빌드로 설정됩니다.
3. 해당 빌드로 롤백할 것인지 확인합니다.

참고

이전 빌드로 롤백하면 선택한 채널에만 영향을 미칩니다. 여러 채널(예: Production, Staging 등)을 사용하는 경우, 영향을 받는 각 채널에 대해 롤백 프로세스를 반복해야 합니다.

롤백 후, 업데이트된 채널을 구독하도록 설정된 기기는 다음 업데이트 확인 시 이전 빌드를 받게 됩니다. 롤백된 빌드는 새로운 업데이트로 처리되므로, 기존의 업데이트 흐름과 조건이 동일하게 적용됩니다.

알림을 통해 긴급 롤백 가속화하기

채널을 다시 지정하면 보통 기기가 다음 번 업데이트를 확인할 때 적용됩니다. Capgo 알림을 사용하면 지원되는 앱이 백그라운드에 있을 때 사일런트 업데이트 확인 알림을 보낼 수 있습니다. updater 통합이 활성화되어 있으면 앱이 설정된 업데이트 모드에 따라 롤백을 확인하고 다운로드 및 설치할 수 있습니다.

이는 가속 경로일 뿐, 강제 플릿 명령이 아닙니다. 배포는 여전히 best-effort 방식이며 운영 체제의 백그라운드 스케줄링, 네트워크 가용성, 기기 상태에 따라 달라집니다. 오프라인이거나 강제 종료된 앱은 업데이트할 수 없으므로 모든 기기에 도달하는 정해진 시간을 보장할 수 없습니다.

이 경로를 설정하려면 다음을 따르세요 알림: 사일런트 업데이트 확인 활성화.

채널 연결 해제

문제를 조사하는 동안 특정 채널의 업데이트를 일시적으로 중단하려면, 현재 빌드에서 채널 연결을 해제할 수 있습니다.

채널 연결을 해제하려면:

1. Capgo Dashboard에서 해당 채널로 이동합니다.

2. 현재 빌드 옆에 있는 “연결 해제” 버튼을 클릭합니다.

3. 채널 연결을 해제할 것인지 확인합니다.

채널 연결이 해제되면 더 이상 새로운 업데이트를 배포하지 않습니다. 해당 채널로 설정된 기기들은 채널이 다시 빌드에 연결될 때까지 현재 빌드를 유지합니다.

업데이트에서 문제를 발견했지만 어떤 빌드로 롤백해야 할지 확신이 서지 않을 때 유용합니다. 채널 연결을 해제하면 추가 업데이트를 배포하지 않고도 문제를 조사할 시간을 벌 수 있습니다.

Built-In Bundle 강제 적용

상황이 더 심각할 경우, 채널의 모든 디바이스를 앱의 Native Build와 함께 처음 패키징되었던 웹 빌드로 되돌리고 싶을 수 있습니다. 이를 “built-in bundle”이라고 합니다.

채널에 built-in bundle을 강제 적용하려면:

1. Capgo Dashboard에서 해당 채널로 이동합니다.

2. “Built-in Bundle” 버튼을 클릭합니다.

3. built-in bundle을 강제 적용할 것인지 확인합니다.

built-in bundle을 강제 적용하면, 해당 채널로 설정된 모든 디바이스는 다음 업데이트 확인 시 원래 패키징된 웹 빌드로 되돌아갑니다. 이는 현재 어떤 빌드를 사용 중인지와 상관없이 적용됩니다.

이 방식은 특정 이전 빌드로 되돌리는 것보다 더 강력한 롤백 옵션입니다. 앱이 마지막으로 App Store 등에 출시된 이후 배포된 모든 Live Update를 폐기하기 때문입니다.

주의

내장 bundle을 강제로 적용하면 해당 채널의 모든 디바이스에 영향을 주므로 주의하세요. 이 작업 전에 영향을 검토하고 후속 계획이 있는지 확인하세요.

이슈 모니터링 및 대응

문제를 빠르게 발견하고 문제가 있는 업데이트의 영향을 최소화하려면 릴리스를 모니터링하고 문제에 대응할 계획을 세우는 것이 중요합니다.

다음과 같은 전략이 있습니다:

아직 코호트로 제한된 롤아웃이라면 다음을 사용해 단계적 배포 채널 전체의 stable bundle을 변경하기 전에 노출을 일시 중지하거나 타겟을 해제하세요.

• 업데이트 배포 직후 크래시 리포트와 사용자 피드백 모니터링
• 전체 배포 전 소규모 그룹에서 업데이트를 테스트하기 위해 단계적 롤아웃 또는 스테이지별 채널 시스템 활용
• 언제 롤백, unlink 또는 내장 bundle을 강제 적용할지, 그리고 누가 해당 권한을 가질지에 대한 명확한 의사결정 프로세스 수립
• 필요한 경우 사용자에게 이슈와 해결 방안을 안내

세심한 모니터링과 문제 있는 업데이트를 빠르게 관리하는 기능을 결합하면, 사용자 불편을 최소화하면서도 지속적으로 개선된 앱 경험을 제공할 수 있습니다.

Rollbacks 다음 단계

사용 중이라면 롤백 롤백 및 버전 관리를 계획하려면, 다음 항목과 연결하세요: 버전 타겟팅 Version Targeting의 구현 상세 내용은 여기를 참조하세요. 업데이트 동작 Update Behavior의 구현 세부 사항은, bundle bundle의 구현 상세 내용은 여기를 참조하세요. Capgo Live Updates Capgo Live Updates의 제품 워크플로우를 위해, Capacitor Live Updates 롤백 전략 Capacitor Live Updates의 롤백 전략에서 실무 맥락을 위해.