sb-front/docs/ANDROID.md

안드로이드 하이브리드 앱 (Capacitor)

Vue dist 를 네이티브 WebView로 패키징해 Android 앱으로 빌드합니다.

구성

• capacitor.config.json — appId kr.sblog.slimbudget, appName Slim Budget, webDir dist
• android/ — 네이티브 프로젝트(커밋됨, 빌드 산출물은 .gitignore)
• .env.capacitor — 앱 전용 환경변수 (vite build --mode capacitor 가 로드)
• src/capacitor.js — 하드웨어 뒤로가기 → 라우터 back, safe-area 클래스(is-native)
• npm 스크립트: build:app, cap:sync, cap:android

⚠️ 빌드 전 반드시 설정

.env.capacitor 의 백엔드 절대 URL 을 운영 도메인으로 교체 (앱 안에선 /api 상대경로가 안 됨):

VITE_API_BASE_URL=https://yourdomain.com/api

백엔드는 이미 CORS에 Capacitor 오리진(https://localhost, capacitor://localhost, http://localhost)을 허용합니다. 백엔드는 HTTPS 여야 합니다(안드로이드 평문 차단).

사전 준비 (PC)

• Android Studio + Android SDK + JDK 17
• 에뮬레이터 또는 실기기(USB 디버깅 on)

빌드 & 실행

# 1) 웹 자산 빌드 + 네이티브로 동기화
npm run cap:sync          # = vite build --mode capacitor && cap sync

# 2) Android Studio 열기 → Run ▶ 으로 에뮬레이터/기기 실행
npm run cap:android       # = cap open android

코드 변경 시마다 npm run cap:sync 후 Android Studio에서 다시 실행.

(선택) 아이콘 · 스플래시

npm i -D @capacitor/assets
# 1024x1024 아이콘을 assets/icon.png 등으로 준비 후
npx capacitor-assets generate --android

배포 (Play Store)

1. Android Studio → Build → Generate Signed Bundle/APK → Android App Bundle(.aab)
2. keystore 생성·보관(분실 시 업데이트 불가) → 서명
3. Google Play Console(계정 1회 $25) → 앱 생성 → .aab 업로드 → 심사

자주 막히는 부분

• 네트워크 안 됨/빈 화면: .env.capacitor 의 VITE_API_BASE_URL 이 실제 HTTPS 백엔드인지, 재빌드(cap:sync) 했는지
• CORS 오류: 백엔드가 앱 오리진 허용하는지(CorsConfig), HTTPS 인지
• 평문 차단: 백엔드가 http면 안드로이드가 차단 → HTTPS 사용
• 로그인 유지: 토큰은 WebView localStorage 에 저장되어 유지됨(정상)