모바일 제공 방식 검토 · 2026-11-19
아동 화면 모바일 제공 방식 비교 — 웹 · PWA · 하이브리드 · 네이티브
마지막 업데이트 2026-11-19
대상: 아동 수업 화면(/client-guest)을 모바일에서 어떤 형태로 제공할지 정하려는 개발자·PM
모바일 문제의 대부분은 iOS WebKit의 오디오 제어 한계에서 나온다. 앱 껍데기(WebView, PWA)만 씌우면 진입 경로·전체 화면 문제는 풀리지만 음성 안정성은 그대로다. 음성 문제를 실제로 풀려면 음성 세션을 네이티브 SDK로 옮기는 하이브리드(H2)가 필요하다.
네트워크 안정성은 제공 방식과 거의 별개다. 443 포트 우회 경로, 재접속 시 세션 유지 같은 서버·프로토콜 쪽 개선이 웹·앱 모두에 이득이다. 추천 순서는 네트워크 개선 + PWA 1단계 → iPad H2 PoC → 필요 시 확대이며, 순수 네이티브는 보류한다.
1. 현재 웹에서 모바일 때문에 생긴 비용
| 문제 | 근거 | 원인 |
|---|---|---|
| TTS 무음·재생 고착 (AudioContext가 suspended·interrupted로 남음) | #838, tts-player.ts:471 | iOS는 사용자 제스처 밖에서 만든 AudioContext를 멈춰 둠 |
| 마이크를 켜면 다른 소리가 작아짐(덕킹) → TTS·영상 소리를 WebRTC loopback으로 우회 | #845, #870, #931, meet-video.tsx:81 | 웹에서는 iOS 오디오 세션(AVAudioSession)을 직접 정할 수 없음 |
| 백그라운드 복귀 시 무음, 재접속 직후 무음 마이크·검은 카메라 | #921, meet-video.tsx:135, use-local-media-stream.ts:10 | 앱 전환 같은 중단 이벤트를 웹이 제대로 받지 못함 |
| iPad AI 음성 밀림, 저전력 모드 감지 | #1084, use-low-power-mode-probe.ts | 저전력 모드에서 화면 갱신(rAF)이 30fps로 고정되고 디코딩도 느려짐 |
| 제스처 밖 출력 기기 변경(setSinkId) 금지 | #979, ai-audio-output-sink.ts:21 | iOS 정책 |
| 카카오·네이버 인앱 브라우저 리다이렉트, "Chrome에서 열기" 유도, 미지원 기기 안내 | #894, #1280, #1286, #835 | 아동이 어떤 브라우저로 들어오는지 통제할 수 없음 |
| Android 태블릿 데스크톱 모드에서 재생 정체 | #1319 | 기기·브라우저 모드가 너무 다양함 |
iOS에서는 Chrome도 내부 엔진이 WebKit이다(EU 제외). "Chrome에서 열기"(#894)를 해도, WebView 하이브리드(WKWebView)로 감싸도, PWA로 홈 화면에 설치해도 위 오디오 제약은 그대로 남는다.
관련 사례: iPad AI 음성 “밀림” 재현 — 저전력 모드 × WebAudio 렌더 부하, setSinkId() 호출 시 시스템 볼륨 슬라이더 미동작 분석.
2. 한눈에 비교
하이브리드 앱은 성격이 크게 다른 두 가지로 나눈다. H1은 기존 웹 화면을 WebView로 감싸기만 하는 얇은 껍데기, H2는 화면은 WebView로 두고 음성 세션만 네이티브 LiveKit SDK로 처리하는 방식이다.
| 항목 | 현재 웹 | PWA | 하이브리드 H1 | 하이브리드 H2 | 네이티브 (Swift / Kotlin) |
|---|---|---|---|---|---|
| iOS 음성 안정성 (덕킹, AudioContext 멈춤, 출력 기기) | ✗ 우회 코드로 버팀 | ✗ 웹과 같음 | ✗ 같은 WebKit | ✓ | ✓ |
| 백그라운드·중단 후 복구 | △ 추정에 의존 | △ 더 빨리 멈출 수 있음 | △ | ✓ | ✓ |
| 네트워크 안정성 | 서버·프로토콜 쪽 개선이 핵심 (방식과 거의 무관) | 약간 유리 (네트워크 전환 감지) | 약간 유리 | ||
| 진입 경로 고정 (인앱 브라우저 회피) | ✗ | ✓ (설치 후) | ✓ | ✓ | ✓ |
| 전체 화면, 오조작 방지 | ✗ | ✓ | ✓ | ✓ | ✓ |
| 화면 꺼짐 방지·권한 유지 | △ | △ iOS는 확인 필요 | ✓ | ✓ | ✓ |
| 리소스 캐시·로딩 속도 | △ | ✓ (service worker) | ✓ | ✓ | ✓ |
| 기존 코드 재사용 | 100% | 거의 100% | 약 95% | UI는 재사용, 미디어 계층은 새로 작성 | 거의 없음 |
| 배포 속도 | 즉시 | 즉시 | UI는 즉시, 껍데기만 심사 | UI는 즉시, 음성 부분은 심사 | 전부 심사 |
| 기능 일치 부담 | 없음 | 없음 | 낮음 | 중간 (웹-네이티브 연동 계약) | 높음 (웹·iOS·Android 3벌) |
| 스토어 정책 (아동 앱, 외부 분석 SDK) | 해당 없음 | 해당 없음 | 적용 | 적용 | 적용 |
| 새로 생기는 위험 | 없음 (현행 유지) | 캐시 때문에 서버-클라이언트 버전 불일치 | Android WebView 버전 편차 | 네이티브와 WebView가 마이크를 함께 씀 (mediasoup 경로) | 플랫폼마다 기능이 어긋남 |
| 필요 인력 | 현 팀 | 현 팀 | 현 팀 + 약간의 모바일 지식 | 모바일 엔지니어 1명 이상 | 플랫폼별 전담 |
| 도입 비용 | 0 | 매우 낮음 | 낮음 | 중간~높음 | 매우 높음 |
3. 방식별 장단점
현재 웹
- 장점: 개발·배포가 가장 빠르고, 링크 하나로 바로 들어온다.
- 단점: 아동이 어떤 브라우저로 들어오는지 통제할 수 없다. iOS 오디오 문제는 우회 코드로 버티고 있어서 관련 수정이 계속 쌓인다.
PWA
- 장점: 비용이 거의 0이면서 진입 경로 고정, 전체 화면, 리소스 캐시를 얻는다. Android에서는 Chrome이 설치형 앱(WebAPK)으로 만들어 줘서 앱에 가깝게 동작한다.
- 단점: iOS 음성 문제는 그대로다. iOS는 설치 과정이 번거롭고, 홈 화면 실행이라는 테스트 환경이 하나 늘어난다. service worker를 넣으면 버전 관리에 주의해야 한다(4장).
하이브리드 H1 (얇은 WebView 껍데기, Capacitor 등)
- 장점: PWA의 효과에 더해 권한 유지, 화면 꺼짐 방지, 기관용 고정 운영(가이드 접근 등)이 확실해지고, iOS 설치도 스토어로 쉬워진다.
- 단점: 음성 문제는 PWA와 같은 수준이다. WebKit이 오디오 세션을 직접 관리해서 네이티브 쪽 설정과 충돌하기 쉽다. Android는 WebView 권한 요청(
onPermissionRequest)을 직접 연결해야 한다. 스토어 심사와 아동 앱 정책 부담은 추가로 생기므로 PWA 대비 추가로 얻는 것이 적다.
하이브리드 H2 (WebView UI + 네이티브 음성)
- 장점: 오디오 세션 카테고리·모드를 직접 정하므로 덕킹 우회용 loopback이 필요 없어지고, 하드웨어 에코 제거와 정식 중단(interruption) 이벤트를 쓸 수 있다. LiveKit은 Swift·Android 공식 SDK가 있어서, Web이 token·dispatch·session config를 만들고 Agent가 Redis에서 읽는 구조를 그대로 둔 채 클라이언트만 바꿀 수 있다. UI는 웹이라 개발 속도도 거의 유지된다.
- 단점 1 (mediasoup): 치료사 영상·화면 공유에 쓰는 Socket/mediasoup SFU 경로는 네이티브 SDK가 사실상 libmediasoupclient(C++)뿐이라 연동이 어렵다. 이 경로를 WebView에 남기면 같은 마이크를 네이티브와 WebView가 동시에 쓰게 된다. H2의 핵심 기술 위험이며 PoC로 먼저 확인해야 한다.
- 단점 2 (연동 계약): 수업 단계 진행, 자료 영상, 종료조건 같은 orchestration(
use-guest-page-session.ts, 약 2,000줄)과 네이티브 오디오 상태 사이의 메시지 규약을 새로 설계해야 한다.
순수 네이티브 (Swift / Kotlin)
- 장점: 안정성·성능 상한이 가장 높다. 저전력·디코딩 제어, 백그라운드 오디오까지 모두 다룰 수 있다.
- 단점: 활동·스텝·자료 영상·오인식 정정 배너 같은 화면을 플랫폼 2개에 다시 구현해야 한다. 기능이 주 단위로 바뀌는 지금 단계에서는 웹·iOS·Android 3곳을 맞추는 비용과 기능 불일치 위험이 크다. 앱 버전과 서버 계약(session config 등)이 맞지 않는 문제도 상시 위험이 된다.
4. PWA 웹앱으로 제공할 때의 장점과 단점
현재 public/에 icon-192x192.png, icon-512x512.png는 있지만 manifest와 service worker는 없다. 즉 지금은 PWA가 아니다. 과거에 next-pwa로 PWA를 운영하다가 Server Action 오류 때문에 제거한 이력이 있다(아래 4-4).
한 줄 요약: PWA는 운영 안정성(진입·오조작·자료 로딩)을 적은 비용으로 높인다. 미디어 안정성(iOS 음성, WebRTC·네트워크)은 바뀌지 않는다. 대신 홈 화면 앱은 잘 새로고침되지 않아 배포 버전 불일치 위험이 커지므로 선행 작업이 필요하다.
4-1. 장점
| 장점 | 설명 | 기존 문제와의 관련 |
|---|---|---|
| 진입 경로 고정 | 홈 화면 아이콘으로 바로 실행되어 카카오·네이버 인앱 브라우저나 지원하지 않는 브라우저를 거치지 않는다. | #1280, #1286, #835의 리다이렉트·차단 처리 부담 감소 |
| 아동 오조작 감소 | display: standalone로 주소창·탭이 없어 뒤로 가기, 새로고침, 탭 전환으로 수업이 끊기는 일이 준다. | 수업 중 이탈·재입장 |
| 화면 공간 확보 | 주소창 높이만큼 화면이 넓어진다. | 낮은 화면에서 입장 입력칸이 잘리는 문제(#1334), 가로 레이아웃(#955) |
| 화면 꺼짐 방지 | Screen Wake Lock API를 쓸 수 있다. iOS는 버전별 지원 차이와 홈 화면 앱 버그 이력이 있어 실기기 확인이 필요하다. | 수업 중 화면 꺼짐 |
| 자료 로딩 안정화 | service worker로 app shell, 아바타·자료 영상을 미리 캐시하면 입장이 빨라지고 약한 회선에서 로딩이 덜 멈춘다. | 리소스 로딩 정체, use-waiting-resource-prefetch 확장 |
| Android는 앱에 가까움 | Chrome이 설치형 앱(WebAPK)으로 만들어 주고 엔진도 Chrome 그대로다. | Android 경험이 가장 크게 개선 |
| 수업 알림 | 웹 푸시. iOS는 16.4 이상이고 홈 화면에 설치한 경우에만 된다. | 수업 시작 알림 |
| 낮은 비용 | 스토어 심사가 없고 배포는 기존 웹 배포와 같다. 코드 재사용 거의 100%. | 웹 개발 속도 유지 |
4-2. 단점·한계
| 단점 | 설명 |
|---|---|
| iOS 음성 문제 그대로 | 홈 화면 앱도 WebKit이다. 덕킹 우회 loopback, AudioContext 멈춤, setSinkId 제약, 저전력 모드 30fps가 모두 남는다(1장). |
| WebRTC·네트워크 변화 없음 | 연결 실패, 업링크 부족, 두 SFU 릴레이 구조의 영향은 그대로다(5장). |
| 기기 성능 문제 변화 없음 | 저사양 기기의 영상 디코딩 과부하(DECODE_OVERLOAD) 등은 같다. |
| 백그라운드에서 더 빨리 멈출 수 있음 | iOS 홈 화면 앱은 Safari 탭보다 백그라운드 정지가 빠른 경향이 있다. |
| 테스트 환경 증가 | iOS 홈 화면 실행 모드는 Safari 탭과 동작이 미묘하게 다르다(과거 권한 반복 요청, 오디오 출력 경로 차이 버그). QA 표에 별도 항목이 필요하다. |
| iOS 설치 번거로움 | 설치 팝업이 없어 공유 → "홈 화면에 추가"를 직접 해야 한다. 보호자용 설치 안내가 필요하다. |
| 입장 흐름 변경 필요 | 홈 화면 아이콘은 항상 같은 start_url로 열린다. 수업마다 링크가 다른 현재 구조와 맞추지 않으면 진입 실패가 오히려 늘 수 있다. |
| 배포 버전 불일치 (가장 큰 위험) | 서버는 새 버전인데 클라이언트는 옛 HTML·JS로 실행되는 문제. service worker 캐시가 직접 원인이 되고, service worker가 없어도 홈 화면 앱은 잘 새로고침되지 않아 "배포를 넘긴 열린 화면"이 브라우저 탭보다 훨씬 자주 생긴다. 4-4 참고. |
4-3. 안정성 관점 정리
| 장애 유형 | PWA 효과 |
|---|---|
| 진입 실패 (인앱 브라우저, 미지원 브라우저) | ✓ 개선 |
| 아동 오조작에 의한 이탈 (뒤로 가기, 탭 전환, 화면 꺼짐) | ✓ 개선 |
| 자료·리소스 로딩 정체 | ✓ 개선 (service worker 도입 시) |
| iOS 음성 무음·덕킹·밀림 | ✗ 변화 없음 |
| WebRTC 연결 실패·끊김, 업링크 부족 | ✗ 변화 없음 |
| 배포 직후 Server Action·청크 로딩 실패 | ⚠ 악화 가능 (선행 작업 필요) |
최근 장애에서 앞쪽 세 유형의 비중이 크면 체감 효과가 크고, 음성·연결 비중이 크면 효과가 작다.
4-4. 과거 Server Action 문제와 현재 상태
| 시점 | 커밋 | 내용 |
|---|---|---|
| 2025-12-09 | 6a1cb3a8 (#43) | next-pwa 제거. 당시 설정은 register: true, skipWaiting: true로, service worker(workbox)가 페이지를 캐시해 옛 HTML·JS가 계속 실행된 것으로 보인다. |
| 2025-12-17 | 5a95e7a1 (#53) | "server action not found" 수정. 설치된 service worker를 전부 해제하고 새로고침하는 ServiceWorkerCleanUp 추가, HTML에 no-cache 헤더. |
| 2026-01-05 | 4ff912ff (#83) | 배포 workflow에서 Server Actions 빌드 키 고정. |
| 2026-01-27 | 3688d2b4 (#155) | 게스트 세션의 sendSdp를 Server Action에서 API Route로 전환. |
| 2026-10~11 | #1244, #1256 | Staging·Prod 빌드 키를 AWS SSM 버전으로 고정. |
해결된 것: service worker가 없어 옛 번들이 오래 남는 경로가 없고, 예전에 설치된 service worker도 app/layout.tsx:45의 ServiceWorkerCleanUp이 지운다. 빌드 키 고정으로 HA 노드 간·키 불일치에 의한 실패 원인도 없어졌다.
남아 있는 위험:
- 아동 입장 화면이 아직 Server Action을 직접 호출한다:
app/client-guest/page.tsx:16에서@/lib/dynamodb의getLesson을 import해:232,:451에서 호출한다. - 배포를 넘긴 열린 화면은 보장되지 않는다:
docs/server-actions-build-key.md에 "버전 사이에서 열린 탭의 Server Actions ID 호환성을 보장하지 않습니다"라고 명시되어 있다. - HTML 캐시 헤더가 다시 느슨해졌다: #53의
no-cache가 지금은private, max-age=0, stale-while-revalidate=300이다(next.config.mjs:44~50, #299에서 변경). 배포 후 최대 5분간 옛 HTML이 먼저 보일 수 있다(브라우저별 지원 차이가 있어 추정). - 자동 복구 장치가 없다:
Failed to find Server Action·ChunkLoadError를 감지해 새로고침하는 처리를 코드와 ppi-docs에서 찾지 못했다. 최근 장애 기록도 없지만, 장애가 없어서인지 기록되지 않아서인지는 구분할 수 없다.
PWA 재도입 시 충돌: 루트 레이아웃의 ServiceWorkerCleanUp은 모든 service worker를 해제하고 새로고침한다. 이 상태로 새 service worker를 넣으면 설치 → 해제 → 새로고침이 반복될 수 있으므로 먼저 정리해야 한다(manifest만 쓰는 1단계에서는 그대로 둬도 된다).
4-5. 옛 버전이 남는 원리 — Server Action과 PWA
한 문장 요약: 브라우저에 남은 옛 버전 화면이 새 버전으로 바뀐 서버에 옛 Server Action ID로 요청을 보내서 실패한다. PWA는 이 "옛 화면이 남아 있는 시간"을 크게 늘린다.
[빌드 시점]
"use server" 함수(getLesson 등)마다 Action ID(해시)를 만든다
├─ 서버: ID → 실제 함수 대응표(manifest)
└─ 클라이언트 JS 번들: getLesson() 호출을 "ID abc123으로 POST"로 바꿔 넣음
[배포 후]
옛 화면 ──POST (Next-Action: abc123, 옛 ID)──▶ 새 서버 (manifest엔 xyz789만 있음)
└▶ "Failed to find Server Action"
- 클라이언트는 함수 이름이 아니라 빌드 때 정해진 ID로 호출한다. 함수를 수정·이동·삭제했거나 빌드 키가 다르면 ID가 바뀐다.
- 같은 원리로 옛 화면이 새 배포에서 지워진 JS 청크를 요청하면
ChunkLoadError가 난다. 둘 다 원인은 화면 버전과 서버 버전이 다르다는 한 가지다. - 문제의 본질은 옛 JS가 아니라 옛 HTML이다. HTML(과 RSC 페이로드)이 어느 JS 청크와 어느 Server Action ID를 쓸지 정한다.
과거 PWA가 이 문제를 키운 이유
- service worker 캐시: 당시
next-pwa(workbox)가 HTML·JS를 캐시해 다음 실행 때 캐시에서 먼저 꺼냈다. 서버를 배포해도 새 service worker가 받아지고 새로고침될 때까지 옛 버전이 유지됐다. "코드 업데이트가 반영 안 된다"는 현상이 이것이다. skipWaiting: true: 새 service worker가 즉시 교체되지만 열린 화면은 옛 JS 그대로라, 한 세션 안에 옛 화면·새 service worker·새 서버가 섞일 수 있었다.- 홈 화면 앱은 거의 새로고침되지 않음: 주소창·새로고침 버튼이 없고 앱 전환 뒤 메모리에서 그대로 이어진다. 며칠 전 화면이 살아 있다가 Server Action을 부르면 실패한다(service worker와 무관).
- 빌드 키 불일치 (PWA와 별개): 빌드 키 고정(#83, #1244, #1256) 전에는 빌드마다 키가 달라 배포 사이·노드 사이 호환이 더 쉽게 깨졌다.
당시 장애 로그는 확인하지 않았으므로 각 원인의 기여도는 추정이다.
설정 단계별로 옛 JS가 남는가
| 구성 | 옛 JS가 남는가 | 이유 |
|---|---|---|
| manifest만 (홈 화면 추가, standalone) | 앱이 살아 있는 동안만 | 캐시 장치가 없어 새로 실행하면 서버에서 HTML을 다시 받는다. 다만 백그라운드에서 다시 열면 이전 페이지가 그대로 이어진다. 열린 탭과 같지만 더 오래 간다. |
| manifest + service worker (해시 정적 파일만 캐시) | 위와 같음 | _next/static/…는 파일 이름에 해시가 있어 새 HTML은 새 파일을 요청한다. 오히려 안전하고 빠르다. |
| manifest + service worker (HTML까지 캐시) | 실행할 때마다 | 캐시된 옛 HTML이 옛 JS를 불러온다. 새 service worker가 적용되기 전까지 앱을 껐다 켜도 옛 버전이다. 과거 next-pwa 문제가 이 유형으로 보인다. |
4-6. service worker 캐시 설정 원칙
HTML 캐시를 끄면 큰 원인은 사라진다. 하지만 "HTML만 캐시 안 하면 끝"은 아니다.
HTML 말고도 캐시하면 안 되는 것
| 요청 | 이유 |
|---|---|
RSC 페이로드 (?_rsc= 쿼리 또는 RSC: 1 헤더) | App Router가 화면 이동 때 HTML 대신 받는 데이터로, JS 청크와 Server Action ID 정보를 담는다. 캐시하면 HTML 캐시와 같은 문제가 생긴다. 가장 놓치기 쉽다. |
| 오프라인 대체 화면 | "네트워크 우선, 실패 시 캐시된 HTML"이면 약한 회선에서 옛 HTML이 다시 나온다. 대체 화면은 고정 오프라인 안내 페이지로 한다. |
| 미리 캐시(precache) 목록 | workbox·next-pwa류 도구가 빌드 산출물을 자동으로 미리 캐시한다. HTML·RSC가 목록에 없는지 확인한다. |
| API·Server Action | Server Action은 POST라 Cache API에 저장되지 않는다. GET API는 runtime 캐시 규칙에서 명시적으로 제외한다. |
그래도 남는 문제
- 살아 있는 페이지: 백그라운드에서 다시 열린 앱은 옛 JS 그대로다. 캐시와 무관하므로 Server Action 제거와 빌드 ID 비교 후 새로고침이 여전히 필요하다.
- 삭제된 청크 요청: 옛 화면이 새 배포에서 지워진 청크를 불러오면
ChunkLoadError. 해시 정적 파일 캐시가 이를 줄이지만, 처음 받은 적 없는 청크는 막지 못하므로 실패 시 새로고침 안전장치가 필요하다. - service worker 교체 시점:
skipWaiting+clients.claim으로 수업 도중 교체되면 캐시 규칙이 세션 중간에 바뀐다. 수업 밖에서 교체한다. ServiceWorkerCleanUp: 루트 레이아웃이 모든 service worker를 해제·새로고침하므로 먼저 정리한다.
권장 설정 요약
navigation(HTML) 요청 → 항상 네트워크 (캐시 저장 X, 캐시 대체 X)
RSC 요청 (?_rsc / RSC:1) → 항상 네트워크
/api/*, POST → service worker 통과 (관여 X)
/_next/static/* (해시 파일) → cache-first (변하지 않는 파일이라 안전)
아바타·자료 영상 → cache-first + 용량 상한
새 service worker → 대기 후 수업 밖에서 교체 (skipWaiting 자동 사용 X)
이 설정에 Server Action 제거와 빌드 ID 비교 후 새로고침을 더해야 과거 같은 업데이트 누락을 사실상 막을 수 있다. 캐시 설정만으로는 부족하다.
4-7. PWA와 service worker의 관계
service worker는 PWA와 별개로 쓸 수 있다. HTTPS 사이트라면 navigator.serviceWorker.register()로 일반 브라우저 탭에서도 등록할 수 있고, manifest나 홈 화면 설치가 필요 없다. "PWA"는 둘을 합쳐 앱처럼 쓰는 방식을 부르는 이름일 뿐이다.
| 구성 요소 | 역할 | 서로 필요한가 |
|---|---|---|
| manifest | 홈 화면 설치, 전체 화면(standalone), 아이콘, 시작 주소 | service worker 없이 단독으로 된다. iOS 홈 화면 추가는 원래 service worker가 필요 없었고, Chrome도 최근 버전부터 설치 조건에서 service worker 필수 요건을 없앴다(버전별 차이 있음). |
| service worker | 요청 가로채기, 캐시, 웹 푸시, 백그라운드 처리 | manifest 없이 일반 브라우저 탭에서도 동작한다. |
- iOS 저장소 삭제: 설치하지 않은 사이트는 7일 동안 방문이 없으면 service worker 캐시를 포함한 저장소를 WebKit이 지울 수 있다(ITP). 홈 화면 앱은 이 제한에서 제외되므로, iOS에서 캐시 효과를 꾸준히 보려면 설치가 유리하다.
- 현재 코드:
ServiceWorkerCleanUp이 모든 service worker를 해제하므로, PWA 여부와 상관없이 service worker를 쓰려면 먼저 정리해야 한다.
| 도입 방식 | 효과 | 위험 |
|---|---|---|
| A. manifest만 | 진입·오조작 개선 | 거의 없음 |
| B. service worker만 (4-6 규칙 적용) | 자료 로딩 개선 | 캐시 규칙을 잘못 정하면 버전 불일치 |
| A + B (완전한 PWA) | 위 효과 모두, iOS 저장소 삭제 제외 | B와 같음 |
어느 방식이든 선행 작업은 같다: 아동 경로의 Server Action 제거, 빌드 ID 비교 후 새로고침, ServiceWorkerCleanUp 정리(4-8).
4-8. 도입 전 선행 작업
- 아동 경로에서 Server Action 제거:
client-guest/page.tsx의getLesson을 API Route로 바꾼다(#155의sendSdp와 같은 방식). 아동 화면에서 Server Action ID 문제가 원천적으로 사라진다. - HTML 캐시 헤더: 최소한
/client-guest는no-cache로 되돌릴지 검토한다. - 버전 감지: 앱이 다시 열릴 때(
visibilitychange)나 수업 입장 전에 서버 빌드 ID와 비교해, 다르면 수업 중이 아닐 때만 새로고침한다.ChunkLoadError·Server Action 실패를 잡아 한 번 새로고침하는 안전장치도 넣는다. ServiceWorkerCleanUp정리: 새 service worker를 넣기 전에 수정한다.- service worker 캐시 원칙(넣는 경우): HTML·API·Server Action 요청은 캐시하지 않고(network-first), 해시가 붙은 정적 파일과 미디어만 캐시한다(cache-first). 과거처럼
skipWaiting으로 수업 중에 갑자기 교체하지 않는다.
1번과 3번은 PWA와 상관없이 현재 웹에도 이득이다.
4-9. 함께 결정할 것
- iOS 브라우저 정책(#894): iOS 16.4 이상은 Chrome에서도 홈 화면 추가가 되지만 엔진은 어느 쪽이든 WebKit이다. "Chrome 유도"를 "홈 화면 앱 유도"로 바꿀지 정한다.
- 입장 방식: 코드 입력·기기 등록으로 "오늘 수업"을 찾는 흐름이나, 링크를 설치된 PWA로 넘기는 흐름 중 하나가 필요하다.
- 적용 범위: manifest
scope를/client-guest로 제한해 치료사·운영자 화면에 영향을 주지 않는다.
4-10. 아동 오조작·연결·권한·장치 항목별 PWA 효과
요약: 탭 관련 오조작은 확실히 줄고, 뒤로 가기는 일부만 줄고, 홈 버튼·WebRTC·권한·장치는 거의 같다. iOS 권한은 오히려 나빠질 가능성도 있다.
| 항목 | PWA 효과 | 설명 |
|---|---|---|
| 브라우저 탭 전환·닫기·새 탭 | ✓ 개선 | standalone에는 탭 바와 주소창이 없어 다른 탭 이동, 탭 닫기, 주소 입력을 할 수 없다. |
| 새로고침 | ✓ 개선 | 새로고침 버튼이 없고, Android의 당겨서 새로고침도 standalone에서는 기본으로 꺼진다. |
| 뒤로 가기 | △ 일부 | 브라우저 뒤로 가기 버튼은 사라지지만 Android 시스템 뒤로 가기(버튼·제스처)는 그대로라 이전 페이지로 가거나 앱이 닫힌다. iOS 가장자리 스와이프 동작도 버전에 따라 다르다. use-prevent-page-leave 같은 이탈 방지는 계속 필요하다. |
| 홈 버튼·홈 스와이프 | ✗ 같음 (iOS는 약간 불리) | OS 홈 동작은 웹·PWA 모두 막을 수 없다. 백그라운드로 가면 마이크가 멈추고, iOS 홈 화면 앱은 Safari 탭보다 더 빨리 정지·종료되는 경향이 있어 다시 열면 처음부터 시작할 수 있다. |
| WebRTC 연결·릴레이 | ✗ 같음 | 같은 엔진·같은 구조다. 두 SFU 연결, AI 음성 릴레이, 업링크 부담 모두 그대로다(릴레이 구조 문서). |
| 마이크·카메라 권한 | △ 같거나 iOS는 주의 | Android 설치 앱은 사이트와 같은 권한을 공유해 동일하다. iOS 홈 화면 앱은 과거에 실행할 때마다 권한을 다시 묻는 버그 이력이 있어 실기기 확인 전까지 위험 요인이다(4-11). |
| 장치 선택 (블루투스 이어폰, 외장 마이크, deviceId 유실) | ✗ 같음 | 장치 열거·선택 API와 OS 오디오 경로가 같다. |
| 장치 경합 (다른 탭·앱·전화) | △ 탭만 일부 | PWA 안에는 탭이 없지만 다른 앱·전화·브라우저로 다시 연 경우는 그대로다(4-12). |
아동 오조작을 실제로 막는 방법
PWA는 브라우저 화면 요소를 없앨 뿐 OS 수준 이탈(홈, 앱 전환, 알림 센터)은 막지 못한다. 기기 기능을 함께 쓴다.
- iOS·iPadOS 사용법 유도(Guided Access): 한 앱에 화면을 고정해 홈 동작, 앱 전환, 특정 영역 터치까지 막는다. Safari와 홈 화면 앱 모두에서 동작한다.
- Android 화면 고정(앱 고정): 현재 앱에 화면을 고정해 홈·최근 앱 이동을 막는다.
- 보호자용 수업 준비 안내에 "화면 고정 켜기"를 넣으면 PWA 여부와 상관없이 효과가 가장 크다.
4-11. 한 번 허용한 권한은 유지되는가
Android(Chrome)는 대체로 유지되지만 iOS는 보장되지 않는다. PWA로 설치했다고 권한이 더 잘 유지되는 것도 아니다.
| 플랫폼 | 동작 | 예외·주의 |
|---|---|---|
| Android (Chrome, 설치 앱 포함) | 권한은 사이트(origin) 단위로 저장되고, 설치 앱(WebAPK)도 같은 Chrome 권한을 공유한다. 탭에서 허용했으면 설치 앱에서도 허용이다. | "이번만 허용"을 고르면 일회성이다. Chrome 안전 점검이 오래 방문하지 않은 사이트 권한을 자동 회수할 수 있다(매주 수업이면 가능성 낮음). OS 설정에서 Chrome 자체의 마이크·카메라를 끄면 모든 사이트가 막힌다. |
| iOS·iPadOS (Safari) | 사이트별 설정은 묻기 / 거부 / 허용이고 기본값이 "묻기"다. 한 번 허용해도 영구 허용으로 저장되지 않아 새 방문·새 세션에서 다시 물을 수 있다. | 유지하려면 주소창 "가가(aA)" → 웹사이트 설정, 또는 설정 앱 → Safari → 카메라·마이크에서 해당 사이트를 "허용"으로 바꿔야 한다. |
| iOS 홈 화면 앱 | 과거 버전에서 실행할 때마다 권한을 다시 묻는 동작이 보고됐다. | 현재 iOS 버전 동작은 확실하지 않으므로 실기기 확인 필요. 다시 묻는다면 iOS에서는 PWA가 권한 측면에서 오히려 불리하다. |
아동 기기는 iPad 비중이 높아 "권한 재요청 → 아동이 거부 → 수업 불가" 경로가 실제로 생길 수 있다(박시현 16회기 태블릿 카메라·마이크 권한 거부 사례).
- 보호자 안내: iOS 사용자에게 사이트 권한을 "허용"으로 바꾸는 방법을 수업 준비 안내에 넣는다(PWA와 무관하게 효과).
- 수업 전 점검: 장치 점검 화면에서 권한 상태를 미리 확인하고, 거부 상태면 기기별 해제 방법을 보여 준다.
- PWA 도입 전 확인: iPad 실기기에서 홈 화면 앱이 실행마다 권한을 다시 묻는지 확인한다.
4-12. 다른 탭·앱과의 장치 경합
경합은 다른 탭보다 OS 수준(다른 앱, 전화, 같은 기기의 다른 페이지)에서 더 많이 생기고, PWA로 바꿔도 대부분 그대로다.
| 경합 상황 | iOS·iPadOS | Android | PWA 효과 |
|---|---|---|---|
| 같은 수업을 두 탭에서 열기 | 나중에 마이크를 잡은 페이지가 이기고, 먼저 연 페이지의 트랙은 mute·종료 | 두 탭이 동시에 마이크 사용 가능, 카메라는 한쪽만 | △ PWA 안에는 탭이 없지만 브라우저에서 링크로 한 번 더 열면 똑같이 생김 |
| 다른 사이트 탭이 마이크·카메라 사용 | WebKit은 동시에 하나의 페이지만 캡처. 다른 탭이 잡으면 우리 트랙이 mute | 마이크는 대체로 공존, 카메라는 배타적 | ✗ 같음 (Safari와 홈 화면 앱이 따로 돌아도 기기 장치는 공유) |
| 다른 앱 (전화, FaceTime, 줌, 음성메모, Siri, 카메라 앱) | 오디오 세션이 중단되고 트랙이 mute. 통화가 끝나도 자동 복구가 보장되지 않음 | Android 10 이상은 앞에 있는 앱이 마이크를 가져가고 백그라운드 앱은 무음을 받음. 카메라는 배타적 | ✗ 같음 |
| 우리 앱 안에서 중복 획득 | getUserMedia를 다시 부르면 이전 트랙이 mute·종료될 수 있음 | 대체로 공존 | ✗ 같음 (코드 설계 문제) |
현재 코드의 대응
- 중복 입장 정리: 서버가 아동 세션 소유권을 확인하고(
claimGuestSessionAdmission,validateLessonSessionOwner,apps/socket/src/sfu-socket/handlers/connection-handlers.ts:1007~1025), 소유권을 잃은 쪽에GUEST_FORCE_KICKED를 보낸다. 강퇴된 쪽이 장치를 즉시 놓는지는 확인하지 않았다. - 앱 내 중복 획득 방지: AI 세션이 마이크를 다시 잡지 않고 대기실 스트림을
externalMicStream으로 받는다(acquire-raw-mic-stream.ts,use-guest-page-session.ts:534). - mute 고착 감지:
use-local-media-stream.ts:9~10이 muted로 얻은 트랙이 일정 시간 안에 unmute되지 않으면 고착으로 판정하고(iOS 재접속 직후 무음 마이크·검은 카메라),mute이벤트를 감시한다(:58~62).
남는 공백 (검토 후보)
- 전화·다른 앱으로 인한 중단 후 복구: mute 후 마이크 재획득과 LiveKit·mediasoup 트랙 교체가 모든 경로에서 동작하는지 점검이 필요하다. 같은 마이크가 두 SFU로 나가는 릴레이 구조라 한쪽만 복구될 수 있다.
- 같은 기기 중복 실행: 서버 강퇴는 있지만 브라우저 쪽 감지는 없다.
BroadcastChannel등 탭 간 통신으로 같은 기기의 중복 실행을 바로 알리면 강퇴 전 짧은 경합도 줄일 수 있다. - 사용자 안내: 수업 중 다른 영상·통화 앱을 쓰지 않도록 안내하고 사용법 유도·화면 고정을 권장한다.
5. 네트워크 안정성 방향
웹이든 앱이든 같은 Wi-Fi·LTE 위에서 같은 libwebrtc를 쓴다. 네이티브의 이점은 네트워크 전환 감지(iOS NWPathMonitor, Android ConnectivityManager)로 미리 ICE 재시작을 하는 정도이고, 기관 방화벽·혼잡 Wi-Fi·NAT 문제는 그대로다. 기존 검토는 2026-11-10 PPI 네트워크 불안정 대책 — 착수 항목 코드 적용성 검토, 2026-11-10 PPI 네트워크 불안정 대책 착수 백로그를 참고한다.
코드에서 확인한 현재 상태
| 영역 | 현재 | 위치 |
|---|---|---|
| 실패 원인 진단 | 연결 실패 시 ICE_DIAGNOSTIC_SUMMARY로 원인 분류 로그 | docs/ice-diagnostics.md (PPI-1327) |
| TURN | Metered 자격 증명을 받아 기본 서버와 합침 | hooks/use-ice-servers.ts, app/api/ice-servers/route.ts |
| LiveKit 연결 설정 | 합친 설정을 rtcConfig로 LiveKit에 넘김 | use-guest-page-session.ts:537 → livekit-client-session.ts:4159 |
| LiveKit 재연결 | 재연결 중 → 복구 이벤트 처리, 복구 후 마이크 입력 상태 재조정 | livekit-client-session.ts:3325~ |
| mediasoup 전송 | announced IP로 UDP·TCP를 직접 받음 | apps/socket/src/sfu-config.ts, transportManager.ts:57 |
| ICE 재시작 훅 | use-ice-restart.ts가 있지만 사용하는 곳이 없음 | grep 결과 |
| Agent 연결 끊김 처리 | 아동이 퇴장하면 AI 세션을 닫고 job도 즉시 종료 | agent.py:382, agent.py:2700 |
| 업링크 대역폭 | 대역폭이 낮으면 카메라 인코딩 단계적 하향 | #1143 |
추천 방향 (우선순위 순)
- 측정:
ICE_DIAGNOSTIC_SUMMARY와 LiveKit 이벤트(connection_reconnecting·recovered·disconnected)를 기관·기기·통신 유형별로 집계한다.udp_path_unresponsive가 많으면 2번, 복구는 되는데 수업이 끊기면 3번, 연결은 유지되는데 소리가 끊기면 4번이 핵심이다. - 443 포트 우회 경로: LiveKit 내장 TURN을 TLS 443으로 열거나 Metered
turns:…:443이 실제로 선택되는지 확인한다. 클라이언트가rtcConfig.iceServers를 넘기면 LiveKit 서버가 내려주는 TURN 목록이 무시될 수 있다(SDK 동작 확인 필요, 추정). mediasoup 포트가 막힌 환경에서 TURN 중계가 적용되는지도 경로별로 확인한다. 기관 IT용 허용 도메인·포트 목록 문서를 만든다. - 장애 복구: LiveKit 완전 재접속(full reconnect) 시 participant 퇴장으로 처리되면 AI 세션과 대화 문맥이 사라질 수 있다(
close_on_disconnect+ 즉시 job 종료, 코드 기반 추정이며 끊김 재현 테스트로 확정 필요). 짧은 유예 시간 동안 세션을 유지하거나, 재접속 시 대화 이력·현재 스텝을 session config로 넘기는 방안을 검토한다. mediasoup은disconnected시restartIce흐름을 연결하고, socket.io 재접속 뒤 producer·consumer 재생성 경로를 점검한다. 재연결 중에는 아동에게 상태를 보여 주고 AI 발화를 잠시 멈춘다. - 음성 우선 품질 저하: 음성에 Opus FEC와 RED(
red,dtxpublish 옵션)가 켜져 있는지 확인한다. 대역폭이 부족하면 아바타 영상 → 카메라 → 오디오 순으로 포기하는 정책을 정한다. 업링크 쪽은 PPI 업링크 stall 웹 대처방안을 참고한다. - 수업 전 네트워크 점검: 장치 점검 화면(#1129)에 실제 서버 대상 UDP·TCP·TURN/TLS 연결 테스트와 RTT·손실률 측정을 추가하고, 결과가 나쁘면 5GHz Wi-Fi 전환 같은 안내를 미리 보여 준다.
- 서버 측: LiveKit·SFU 리전과 증설 여력, Redis/Valkey 단일 장애점 여부를 운영 환경에서 확인한다(LiveKit 서버 설정은 저장소에 없음).
관련 사례: 석우주 8회기 아동 화면 미표시·AI 세션 실패 — iPad WebKit ICE 후보 미수집 원인 분석.
6. 공통 고려사항 (앱 방식 선택 시)
- 앱스토어 정책: 아동 대상 앱이라 Kids 카테고리에 들어가면 외부 분석 SDK가 제한된다. 현재 게스트 화면의 LogRocket(
app/client-guest/logrocket-guard.tsx)은 앱에서 쓰기 어려울 수 있다. 음성 데이터 수집 고지도 심사 대상이다. - 버전 공존: 앱은 업데이트하지 않은 옛 버전이 계속 남는다. 강제 업데이트 장치와 서버의 하위 호환 정책이 필요하다.
- Android는 효과가 작음: Chrome의 WebRTC·Web Audio가 비교적 안정적이라 네이티브 이득이 iOS보다 훨씬 작다. 우선순위는 iOS·iPad다.
7. 추천 경로
- 지금: 네트워크 개선(443 우회 경로, 재접속 시 세션 유지, mediasoup ICE 재시작)과 PWA 1단계(manifest·standalone·scope, Wake Lock, 설치 안내. service worker 제외)를 병행한다. 비용이 작고 웹·앱 어느 쪽에도 이득이 남는다. PWA 전에 아동 입장 화면의 Server Action(
getLesson)을 API Route로 바꾸고 버전 감지를 넣는다(4-8). - 실기기 측정: 홈 화면 실행 모드를 iOS·Android에서 QA하고, 진단 로그에 실행 모드(
display-mode)를 넣어 Safari 탭과 지표를 비교한다. 효과가 확인되면 4장의 캐시 원칙으로 service worker를 추가한다. - iOS 음성 문제가 여전히 주요 원인이면: iPad 기준 H2 PoC(2~4주 규모)로 덕킹·무음·백그라운드 복귀·저전력 지표를 기존 웹과 비교하고, mediasoup 경로와 마이크 공유 가능성을 확인한다. 효과가 확인되면 iOS부터 H2로 출시하고 Android는 웹·PWA를 유지한다.
- H1은 건너뛴다: PWA와 효과 차이가 작다. 기관 기기 일괄 배포처럼 스토어 배포 자체가 필요할 때만 검토한다.
- 순수 네이티브는 보류: 제품 UI가 안정되고 모바일 전담 인력이 생긴 뒤 검토한다.
근거와 검증 범위
- PPI
develop(2026-11-19, 658debb9) 기준apps/web/entities/guest-session/,apps/web/entities/guest-page-session/,apps/web/shared/ui/meet-video.tsx,apps/web/hooks/(use-ice-servers,use-ice-restart,use-low-power-mode-probe,use-kakao-browser-redirect),apps/web/lib/voice-agent/livekit-client-session.ts,apps/socket/src/sfu-config.ts,apps/livekit-agent/agent.py,apps/web/public/,docs/ice-diagnostics.md. - PWA·Server Action 이력은
6a1cb3a8,5a95e7a1,4ff912ff,3688d2b4, #1244, #1256 커밋과 현재apps/web/next.config.mjs,apps/web/app/layout.tsx,apps/web/components/ui/service-worker-clean-up.tsx,apps/web/app/client-guest/page.tsx,docs/server-actions-build-key.md로 확인했다. - 모바일 관련 이력은
git log의 iOS·Safari·iPad·Android·카카오·AudioContext 관련 커밋 메시지로 확인했다. - WebKit 엔진 정책, iOS PWA 기능(웹 푸시 16.4+, Wake Lock), 앱스토어 Kids 카테고리 정책, livekit-client의
rtcConfig우선순위는 일반 지식 기반이며 최신 정책·SDK 동작은 별도 확인이 필요하다. - LiveKit 완전 재접속 시 Agent 세션 종료 여부, 각 방식의 실제 안정성 개선 폭은 실기기·재현 테스트로 측정하지 않았다.
관련 PPI 문서
- 아동 측 WebRTC 릴레이 구조 — LiveKit · mediasoup 두 SFU (시각화): 아동 기기가 두 SFU 사이에서 AI 음성을 재송출하는 구조와 네이티브 전환 시 영향.
- 2026-11-10 PPI 네트워크 불안정 대책 — 착수 항목 코드 적용성 검토: 네트워크 개선 착수 항목의 코드 적용성.
- 2026-11-10 PPI 네트워크 불안정 대책 착수 백로그: 네트워크 대책 백로그.
- PPI 업링크 stall 웹 대처방안: 업링크 대역폭 저하 대응.
- 저사양 기기 분류 기준: 기기 성능별 지원 기준.
- iPad AI 음성 “밀림” 재현 — 저전력 모드 × WebAudio 렌더 부하: iOS WebAudio 제약 사례.
- 석우주 8회기 iPad WebKit ICE 후보 미수집 원인 분석: iPad WebKit 연결 실패 사례.