Shorebird OTA 트러블슈팅

배경

Flutter 앱에 Shorebird OTA(Over-The-Air) 업데이트를 적용하려고 했다. 패치를 배포하고 테스트 디바이스에서 확인했는데, "This app reports version 1.0.0+1, but the binary is different from the version 1.0.0+1 that was submitted to Shorebird" 라는 오류가 발생했다.

분명히 같은 버전인데 왜 바이너리가 다르다고 하는 걸까?

---

개념 분해

Release (릴리스)

• 역할: OTA 패치의 기준점이 되는 빌드를 Shorebird 서버에 등록
• 위치/범위: shorebird release android 명령으로 생성, 서버에 바이너리 "지문(fingerprint)" 저장

Patch (패치)

• 역할: Release 기준으로 변경된 코드만 추출하여 OTA로 전송
• 위치/범위: shorebird patch android 명령으로 생성, 해당 Release 버전 앱에만 적용

바이너리 지문 (Binary Fingerprint)

• 역할: 빌드된 앱의 고유 식별자. 코드, 의존성, 빌드 시점 등이 모두 반영됨
• 위치/범위: 앱 바이너리 내부에 저장, Shorebird가 패치 적용 전 검증

문제 상황 재현

잘못된 워크플로우

1. flutter build appbundle → Play Store 배포 (빌드 A)
2. 시간 경과 후 shorebird release android (빌드 B)
3. shorebird patch android
4. 테스트 디바이스에서 패치 다운로드 시도
5. 실패 ❌

실제 오류 로그

[ShorebirdService] Update status: UpdateStatus.outdated
[ShorebirdService] Downloading update...
updater::network: [shorebird] Sending patch check request: PatchCheckRequest {
  app_id: "196f2538-1d47-47af-bb9f-4df97ced7743",
  channel: "stable",
  release_version: "1.0.0+1",
  platform: "android",
  arch: "aarch64"
}
updater::updater: [shorebird] Patch check response: PatchCheckResponse {
  patch_available: true,
  patch: Some(Patch { number: 1, hash: "1cc07ad13c..." })
}
updater::network: [shorebird] Downloading patch from: https://cdn.shorebird.cloud/...
updater::network: [shorebird] Wrote patch to: ".../downloads/1"
updater::updater: [shorebird] Patch successfully applied to ".../downloads/1.full"
[ShorebirdService] Update failed: [ShorebirdUpdater] UpdateException:
  This app reports version 1.0.0+1, but the binary is different from
  the version 1.0.0+1 that was submitted to Shorebird. (unknown)

인과관계 추적

원인: Play Store 배포 빌드 ≠ Shorebird Release 빌드
  ↓
중간: 패치 다운로드는 성공하지만 바이너리 검증 실패
  ↓
결과: UpdateException 발생, 패치 적용 안됨

---

해결 방법

올바른 Shorebird 워크플로우

1. shorebird release android
   → "Would you like to continue? (y/N)" → y 입력

2. 생성된 AAB를 Play Store에 배포
   → build/app/outputs/bundle/release/app-release.aab

3. 사용자가 Play Store에서 설치

4. 코드 수정 후 패치 배포
   → shorebird patch android

5. 사용자 앱 재시작 시 OTA 적용 ✅

---

핵심 정리

Release = OTA의 기준점 (반드시 이 빌드를 스토어에 배포)
Patch = Release 기준의 차이점만 전송
바이너리 지문 = 빌드마다 고유, 일치해야 패치 적용
별도 빌드 → 스토어 배포 = OTA 불가능 ❌
Shorebird Release → 스토어 배포 = OTA 가능 ✅