DETOX ENGLISHMagic Read AI 웹 매뉴얼
교재 PDF실습 키트

CHAPTER 09

폰과 아이패드에 설치하기

지금까지 만든 앱은 웹 기술로 만들었지만, 설치할 수 있는 웹 앱(PWA)으로 만들면 앱 스토어에서 받은 앱처럼 홈 화면 아이콘으로 열리고, 주소창 없이 한 화면을 다 쓰고, 인터넷이 끊겨도 읽기와 단어 시험이 됩니다. 수업에서는 데스크톱에 먼저 설치하고, 폰과 아이패드는 앱을 인터넷에 올린 뒤 설치합니다.

1. 설치할 수 있는 앱으로 만들기

Opus 5.5 권장설치할 수 있는 앱으로
이 앱을 데스크톱(Chrome·Edge·Safari), 안드로이드, 아이폰·아이패드에 설치되는 PWA로 만들어 줘.
- vite-plugin-pwa 2, registerType 'prompt'. 앱 아이콘은 DESIGN.md의 대표 요소로 SVG를 하나 만들고 @vite-pwa/assets-generator로 크기별 아이콘(192·512, 마스커블, 애플 터치 아이콘 180)과 아이폰 시작 화면을 만든다.
- manifest: id와 start_url은 "/", 이름 "Magic Read AI", 짧은 이름 "Magic Read", 설명, display "standalone", 배경색과 theme-color는 DESIGN.md의 종이색. 스크린샷 폰용 2장·데스크톱용 2장(설치 창이 풍성해진다). 바로가기: 단어장, 단어 시험.
- index.html: viewport-fit=cover, theme-color, 애플 터치 아이콘, 아이폰 시작 화면 링크. 화면 위아래 막대는 env(safe-area-inset-*)로 노치를 피한다.
- 오프라인: 앱 파일은 미리 저장. /api/*는 항상 인터넷으로(NetworkOnly). 인터넷이 없으면 AI 버튼에 '인터넷 연결이 필요해요'.
- 새 버전이 나오면 '새 버전이 있어요 · 다시 불러오기' 알림. 글을 쓰는 중에는 저절로 새로 고치지 않는다.
- 설치 안내: Chrome·Edge는 [앱 설치] 버튼, 아이폰·아이패드는 '공유 → 홈 화면에 추가' 안내 한 번. 카카오톡 같은 앱 속 브라우저로 열었으면 'Safari나 Chrome으로 열어야 설치할 수 있어요'.
다 되면 Chrome 개발자 도구의 Application 탭 기준으로 설치 조건을 점검해 줘.

2. 데스크톱에 설치하기

내 컴퓨터에서 띄운 앱(http://localhost:5173)도 데스크톱에는 설치할 수 있습니다. 설치 아이콘이 안 보이면 Claude에게 "설치해 볼 수 있게 빌드해서 띄워 줘"라고 보내세요(개발 모드에서는 설치에 필요한 파일이 꺼져 있는 경우가 많습니다).

브라우저설치하는 법
Chrome (Windows·Mac)주소창 오른쪽 끝의 설치 아이콘 → 설치. 안 보이면 ⋮ 메뉴 → 전송, 저장 및 공유 → 페이지를 앱으로 설치
Edge (Windows·Mac)주소창의 '앱 사용 가능' 아이콘 → 설치. 작업 표시줄이나 시작 메뉴에 고정할 수 있습니다
Safari (Mac, macOS Sonoma 이상)파일 메뉴 → Dock에 추가 → 추가

3. 인터넷에 올리기 (Cloudflare, 무료)

폰과 아이패드는 내 컴퓨터의 localhost에 들어올 수 없으니 앱을 인터넷 주소에 올립니다. Cloudflare의 무료 요금제로 화면 파일은 무제한, 서버는 하루 10만 번 요청까지 씁니다. 혼자 쓰는 앱에는 남는 양입니다.

  1. 브라우저에서 dash.cloudflare.com에 들어가 무료 계정을 만듭니다(이메일 인증까지).
  2. 아래 상자를 보냅니다. 중간에 브라우저가 열려 Cloudflare 로그인 허락을 물으면 Allow를 누르세요.
Sonnet 5.5 권장인터넷에 올리기
이 앱을 Cloudflare Workers에 배포해 줘. 화면 파일과 /api 서버를 Worker 하나로.
- 먼저 npx wrangler login 으로 로그인을 도와줘.
- 비밀값은 내가 직접 넣을 수 있게 명령만 알려 줘: npx wrangler secret put ANTHROPIC_API_KEY, npx wrangler secret put APP_PASSCODE (키를 대화창에 쓰지 않는다).
- 서버는 x-app-passcode 머리글을 확인하고, 입력 길이와 max_tokens를 제한하고, 1분에 30번 넘는 요청은 잠시 막는다.
- 배포가 끝나면 https 주소를 알려 주고, 그 주소로 들어가 설정 화면에 암호를 넣는 법을 안내해 줘.

Claude가 알려 준 npx wrangler secret put … 명령은 VS Code 위쪽 메뉴 Terminal → New Terminal을 열어 붙여 넣고 Enter를 누릅니다. 키를 물으면 붙여 넣고 Enter를 누르세요. 화면에 글자가 보이지 않아도 들어갑니다.

4. 폰과 아이패드에 설치하기

설치 전에 두 가지를 기억하세요. 카카오톡으로 받은 앱 주소를 누르면 카카오톡 안의 브라우저로 열리는데, 거기서는 설치가 안 됩니다. 그리고 아이폰·아이패드는 설치한 앱과 Safari가 저장 공간을 따로 씁니다. 그래서 먼저 설치하고, 설치한 앱에서 단어를 모으기 시작하는 편이 안전합니다.

기기설치하는 법
아이폰·아이패드 (iOS·iPadOS 26 이상)Safari로 앱 주소 열기 → 공유 버튼(없으면 ••• → 공유) → 홈 화면에 추가 → '웹 앱으로 열기'가 켜진 것을 확인 → 추가
아이폰·아이패드 (iOS·iPadOS 18 이하)Safari로 앱 주소 열기 → 공유 버튼 → 홈 화면에 추가 → 추가
안드로이드 (Chrome)⋮ 메뉴 → 설치 및 바로가기 만들기(또는 홈 화면에 추가) → 설치
삼성 인터넷주소창의 설치 아이콘, 또는 메뉴의 홈 화면에 추가
카카오톡에서 열었을 때안드로이드: ⋮ → 다른 브라우저로 열기. 아이폰: 공유 버튼 → Safari로 열기. 그다음 위 순서대로

5. 기기를 바꿔도 단어장 지키기

방법어떻게어울리는 사람
파일로 옮기기 (기본)설정 → 백업 → 내보내기로 파일을 만들어 카카오톡 나에게 보내기나 iCloud Drive로 옮기고, 다른 기기의 앱에서 가져오기누구나. 무료, 계정 필요 없음
Dexie Cloud단어장 저장 도구(Dexie)의 동기화 서비스. 무료 요금제는 3명까지데스크톱과 아이패드를 매일 같이 쓰는 사람
내 Cloudflare 데이터베이스이미 쓰는 Cloudflare에 D1을 붙여 직접 동기화로그인과 합치기 규칙까지 직접 정하고 싶은 사람

앱 스토어에 올리려면 (선택)

혼자 또는 가족이 쓰는 앱이라면 설치형 웹 앱으로 충분합니다. 스토어에 올리고 싶다면 비용과 조건은 이렇습니다.

스토어비용조건
Microsoft Store개인 개발자 등록 무료PWABuilder로 지금 앱을 그대로 묶어 올릴 수 있습니다. 가장 쉬운 곳
Google Play등록비 25달러(한 번)새 개인 계정은 테스터 12명과 14일 비공개 테스트를 먼저 거쳐야 합니다
Apple App Store해마다 99달러Mac과 Xcode가 필요하고, '웹사이트를 포장만 한 앱'은 심사 지침 4.2로 거절될 수 있습니다. Capacitor로 기기 기능을 더해야 통과 가능성이 생깁니다

집에서 이어 하기

  • 공유받기: 설치한 앱으로 기사 글을 공유하면 바로 책으로 들어오게(안드로이드·데스크톱 Edge)
  • 내 앱 소개 화면: 설치 창에 보이는 스크린샷을 내 디자인으로 다시 찍기
  • Microsoft Store에 올려 보기: PWABuilder(pwabuilder.com)에 내 앱 주소를 넣고 안내를 따라가기