하이브리드 앱 브릿지 계약이 없으면 생기는 장애 유형
하이브리드 앱은 “웹 화면 + 스마트폰 본연의 기능”을 합친 형태입니다.
웹 화면은 빠르게 고칠 수 있습니다. 그런데 카메라·푸시·파일·생체인증·외부 결제 앱 실행은 앱 안쪽 통로(브릿지) 를 통합니다.
이 통로에 대한 약속—이름, 주고받는 값, 성공·실패 코드, 버전이 없으면 문제가 납니다. 웹만 배포했는데 iOS만 멈추거나, 특정 기종만 업로드가 실패하거나, 구버전 앱에서 로그인만 무한 로딩이 납니다.
많은 프로젝트가 “일단 연결해 두고” 문서화하지 않습니다. 초기에는 동작해 보이지만, 인원이 바뀌거나 웹·앱 배포 주기가 어긋나는 순간 재현 어려운 장애로 돌아옵니다.
왜 이런 일이 생기나요?
브릿지는 앱 안 웹 화면의 스크립트와, 스마트폰 쪽 코드가 서로 기능을 호출하는 통로입니다. 형태는 프로젝트마다 달라도 역할은 비슷합니다.
| 방향 | 예시 | 실패 시 사용자 체감 |
|---|---|---|
| 웹 → 앱 | 카메라 열기, 파일 선택, 푸시 토큰 요청 | 버튼 무반응, 빈 화면 |
| 앱 → 웹 | 푸시로 특정 페이지 열기, 뒤로가기, 결제 앱 복귀 | 잘못된 페이지, 뒤로가기 깨짐 |
| 양방향 | 로그인 유지 정보 공유, 세션 갱신 | 로그아웃 루프, 로그인 반복 |
핵심은 호출 이름 문자열 하나가 곧 약속이라는 점입니다. 일반 서버 API처럼 자동 문서가 잘 나오지 않으므로, 팀 합의 문서가 곧 계약입니다.
자주 나오는 장애 유형은 이렇습니다.
1) 이름만 살짝 다른 경우
웹은 `getFcmToken`, 앱은 아직 `getPushToken`을 기다립니다. 화면은 “알림 설정 중…”에서 멈춥니다. 로그에 남는 에러가 약해 네트워크 문제로 오진하기 쉽습니다.
2) 보내는 값의 형식이 다른 경우
웹이 `{ fileId: 12 }`를 보내고 앱은 `{ idx: 12 }`만 읽습니다. 일부 기기에서만 기본값이 들어가 간헐 성공이 되어 더 위험합니다.
3) 응답이 영원히 안 오는 경우
권한 팝업을 사용자가 무시하면 응답이 안 올 수 있습니다. 웹 UI는 로딩만 돌립니다. 약속에 시간 제한·취소 코드가 있어야 합니다.
4) 권한·타이밍 문제
카메라 권한 거부 후 재요청, 백그라운드에서 호출 등 OS 제약이 웹 개발자에게 안 보입니다. “웹 로컬에서는 되는데”가 반복됩니다.
5) 푸시·뒤로가기 스택이 깨지는 경우
푸시로 상세에 들어간 뒤 뒤로가기 시 로그인·메인으로 튕기거나 빈 화면이 남습니다. 앱 쪽 화면 쌓기 정책과 웹 이동 규칙이 한 약속으로 정의되지 않은 경우입니다.
6) 버전 없이 호환을 깨는 변경
웹이 새 필드를 필수로 바꾸면 구버전 앱 전량이 장애입니다. 스토어 강제 업데이트 전 사용자 비중이 클수록 피해가 큽니다.
7) 보안·토큰 유출 경로
브릿지로 로그인 유지 정보를 평문 로그에 찍거나, 임의 도메인에서 앱 기능을 열어두면 세션 탈취 면적이 커집니다. 허용 도메인·허용 기능 목록이 약속의 일부여야 합니다.
이렇게 보면 쉬워요
최소 브릿지 약속 문서에 넣을 항목입니다.
| 항목 | 설명 |
|---|---|
| 기능 이름 | 고정 문자열, 대소문자 규칙 |
| 요청 형식 | 필수/선택 필드, 타입 |
| 응답 형식 | 성공/실패 공통 틀 |
| 오류 코드 | 권한거부, 미지원, 시간초과, 사용자취소 |
| 버전 | 통로 버전 또는 기능별 버전 |
| 최소 앱 빌드 | 이 웹 기능에 필요한 최소 앱 버전 |
| 보안 | 호출 가능 도메인, 민감정보 로깅 금지 |
| 샘플 | 웹 1, 앱 1 샘플 호출 |
이렇게 준비하면 좋아요
- 기능 탐지
앱이 해당 기능을 지원하는지 먼저 묻고, 없으면 웹 대체 UI를 씁니다. - 하위 호환
새 필드 추가 시 구버전은 무시하고, 필수로 바꿀 때는 최소 앱 버전과 함께 갑니다. - 관측
기능별 성공/실패/시간초과 횟수를 남깁니다(개인정보 제외). - 배포 순서
앱을 먼저 올리고 → 웹 기능을 켭니다. - 약속 테스트
출시 전 체크리스트에 “브릿지 스모크”를 넣습니다.
외주에서 웹 팀과 앱 팀이 분리되면 장애 확률이 올라갑니다. “일단 웹 배포, 앱은 다음 주”가 되면 약속 위반 상태가 운영에 노출됩니다. 한 업체가 웹·앱 껍데기·브릿지 문서를 같이 소유하거나, 최소한 통합 테스트 책임을 명시한 계약이 필요합니다.
인수인계 시 화면 소스만 전달하고 브릿지 스펙이 빠지면, 다음 유지보수 업체가 앱 쪽을 건드릴 때마다 회귀가 납니다. 산출물 목록에 브릿지 스펙 최신본·샘플 로그·최소 앱 버전 표를 넣는 것이 소스 코드만큼 중요합니다.
자주 하는 실수
- 장애 재현에 기기 대여·구버전 앱 확보가 필요해 복구가 길어짐
- “앱 재설치 해보세요” 응대가 반복되며 브랜드 신뢰 하락
- 브릿지 전면 재작성 시 웹 화면 전수 재검수
- 보안 사고 시 책임 소재가 웹/앱 업체 간 공방으로 번짐
- □ 브릿지 기능 목록이 단일 문서로 존재한다
- □ 모든 기능에 성공/실패 틀과 시간 제한이 있다
- □ 웹 배포 전 최소 앱 버전 검사가 있다
- □ 허용 도메인 목록이 운영 빌드에 적용된다
- □ 푸시 진입·뒤로가기 시나리오 테스트가 있다
- □ 파일 업로드·카메라·결제는 실기기 점검 대상이다
- □ 장애 시 웹 대체 또는 기능 끄기 경로가 있다
LB Contents는 하이브리드 앱 제작 시 웹 화면과 앱 브릿지 약속을 한 흐름으로 설계·구현합니다. “웹은 되는데 앱만 안 된다” 유형을 줄이려면, 기능 기획 단계부터 브릿지 경계를 같이 그리는 것이 안전합니다. 요구사항이 정리되기 전 상담도 가능합니다.