모바일 설정 흐름

Akan 모바일 앱은 CSR 웹 앱을 Capacitor Android/iOS shell 안에서 실행합니다. 웹 앱은 페이지와 비즈니스 로직을 담당하고, 네이티브 shell은 패키지 식별자, 디바이스 권한, 플러그인 링크, 네이티브 파일, signing, 스토어 빌드를 담당합니다.

먼저 모바일 식별자를 정하고, 앱에서 실제로 쓰는 Capacitor 플러그인만 선언한 뒤, Android와 iOS 빌드를 준비합니다. Push notification과 deep link는 선택 기능이므로 앱에 필요할 때만 설정하세요.

1. mobile config

앱 이름, package id, 버전, target basePath, 권한, 네이티브 파일을 정합니다.

2. Capacitor plugins

이 앱에서 쓰는 네이티브 플러그인을 apps/myapp/package.json에 선언합니다.

3. Android / iOS

플랫폼 도구, app ID, signing, sync/build 명령을 준비합니다.

Mobile Config

akan.config.ts의 mobile 블록은 네이티브 패키지를 설명합니다. 이 값은 Android application metadata, iOS bundle metadata, target 진입 경로, 네이티브 권한 힌트, 네이티브 파일 복사 규칙으로 반영됩니다.

apps/myapp/akan.config.ts

appName: 네이티브 표시 이름입니다. 플랫폼이나 스토어가 덮어쓰지 않는 한 런처/홈 화면에서 보입니다.

appId: 고정 네이티브 패키지 식별자입니다. Android는 applicationId/package name으로, iOS는 bundle id로 사용합니다. 플랫폼 콘솔에 앱을 등록할 때도 정확히 같은 값을 써야 합니다.

version / buildNum: version은 사용자에게 보이는 버전이고, buildNum은 스토어 제출용 빌드 번호입니다. 네이티브 스토어 제출마다 buildNum을 올려야 합니다.

targets.default.basePath: 네이티브 앱이 여는 Akan client route입니다. 하나의 앱 repo에서 고객/관리자/파트너 앱을 따로 배포할 때 target을 나눕니다.

permissions: "camera", "contacts", "location", "push" 같은 네이티브 기능 힌트입니다. Akan 쪽 네이티브 metadata를 준비하지만, 플러그인별 세부 설정은 여전히 필요할 수 있습니다.

files: 앱 폴더의 파일을 생성된 네이티브 프로젝트 경로로 복사합니다. Android/iOS 프로젝트 안에 들어가야 하는 네이티브 설정 파일에 사용합니다.

릴리즈 후 appId는 가볍게 바꾸면 안 됩니다. Android와 iOS는 다른 appId를 완전히 다른 앱으로 봅니다.

Capacitor Plugins

Capacitor는 앱 package에 선언된 네이티브 플러그인을 링크합니다. workspace 전체에 dependency가 있어도 앱 package에 선언되어 있지 않으면 부족합니다. 앱에서 실제로 호출하는 플러그인만 넣으세요.

Base mobile shell dependencies

Push notification add-on dependencies

*를 쓰는 이유는 앱 package가 resolved version이 아니라 사용 여부만 선언하기 때문입니다. 실제 설치 버전은 workspace lockfile과 root package가 관리합니다.

start-ios/start-android는 Capacitor add/sync/run 명령을 실행하지만 apps/myapp/package.json에 dependency를 추가하지는 않습니다. 먼저 app dependency를 선언한 뒤 mobile 명령을 다시 실행하세요.

Usually package-only: haptics, device 같은 작은 bridge 플러그인은 package 선언 후 sync만으로 동작하는 경우가 많습니다.

Package + native settings: camera, geolocation, push, background 작업, file access, auth 플러그인은 Info.plist, AndroidManifest, Xcode capability, Gradle 설정, 콘솔 credential이 필요한 경우가 많습니다.

After changing plugins: 플러그인을 추가/제거한 뒤에는 start-ios/start-android 또는 build 명령을 다시 실행하세요. 이때 네이티브 플러그인 파일이 갱신됩니다.

Android Setup

Android 설정은 에뮬레이터나 실기기에서 빌드/실행 가능한 Android 프로젝트를 준비하는 과정입니다. 핵심은 package name 일치입니다. mobile.appId와 생성된 Android applicationId가 같아야 합니다.

준비물

Android SDK가 설치된 Android Studio.
터미널에서 사용할 수 있는 JDK 21.
com.example.shop 같은 고정 mobile.appId.

1. Configure local toolchain

2. Set Android package identity

3. Sync and build

start-android: 개발 중 사용합니다. 네이티브 파일을 준비하고 에뮬레이터나 연결된 기기에서 앱을 실행합니다.

build-android: 기기 실행 없이 Android 프로젝트가 빌드되는지 확인할 때 사용합니다.

release-android: AAB 같은 스토어 산출물을 만들 때 사용합니다. 이 단계에서는 release signing과 Play Store 설정이 중요합니다.

성공 확인

생성된 applicationId가 mobile.appId와 같습니다.
앱이 에뮬레이터나 실기기에서 실행됩니다.

Push 알림은 Push Setup에서 다룹니다. Android Setup에서는 먼저 네이티브 프로젝트와 package identity만 확인하세요.

iOS Setup

iOS 설정은 Xcode 프로젝트, bundle identity, signing, 시뮬레이터 실행, 스토어 빌드를 준비하는 과정입니다. Push 알림은 Push Setup에서 다룹니다.

준비물

설치된 Xcode.
iOS bundle id로 사용할 고정 mobile.appId.
실기기 실행이나 릴리즈를 위한 Apple signing 설정.

Xcode 확인

sync 후 생성된 iOS 프로젝트를 엽니다.
bundle identifier가 mobile.appId와 같은지 확인합니다.
실기기에서 실행한다면 signing team과 provisioning을 확인합니다.
먼저 시뮬레이터에서 실행하고, 기기 전용 기능은 실기기에서 확인합니다.

1. Sync and build

Push 알림은 Push Setup에서 다룹니다.

Push Setup

Push 설정은 web push, Android push, iOS push 세 영역으로 나뉩니다. Akan은 usePushNotification() 하나의 client API를 제공하지만, 플랫폼 설정은 여전히 다릅니다.

Akan이 자동 처리

web push용 /firebase-messaging-sw.js 서빙.
target.permissions에 push가 있을 때 Android POST_NOTIFICATIONS 권한 추가.
iOS aps-environment, remote-notification background mode, Capacitor AppDelegate bridge 생성.

사용자가 준비

Capacitor push와 FCM용 app package dependency.
Firebase web config, google-services.json, GoogleService-Info.plist.
Firebase Console 앱 등록과 APNs credential.

Web push

Firebase Console에서 web 앱을 만들거나 기존 web 앱을 엽니다.
공개 가능한 Firebase web config를 env.client.*에 넣습니다.
Web Push certificate key pair를 만들고 VAPID public key를 vapidKey에 넣습니다.
Akan은 client Firebase config를 사용해 /firebase-messaging-sw.js를 자동으로 서빙합니다.

apps/myapp/env/env.client.local.ts

Android push

Firebase Console에서 프로젝트를 엽니다.
Android 앱을 추가합니다.

Android push file copy

google-services.json은 client/native Firebase 설정 파일입니다. Firebase Admin service account JSON이 아닙니다. 서버 credential은 env.server.*에 둡니다.

Android notification details

Android는 token 등록과 별개로 알림 표시 설정이 더 필요할 수 있습니다. 주문 업데이트나 채팅처럼 고정 카테고리가 필요하면 channel을 만들고, 런처 아이콘이 알림 아이콘으로 맞지 않으면 네이티브 프로젝트에서 기본 icon/color를 설정하고, 앱 실행 중 foreground 표시 방식도 앱 코드에서 결정하세요.

iOS push

Firebase에서 mobile.appId와 같은 bundle id로 iOS 앱을 등록합니다.
GoogleService-Info.plist를 다운로드합니다.

iOS push file copy

GoogleService-Info.plist는 앱 폴더에 두고, mobile.files로 생성된 iOS 프로젝트에 복사하세요. simctl push는 오는데 Firebase Console 토큰 발송이 안 오면 빌드된 aps-environment와 맞는 APNs development/production credential을 확인하세요.

APNs environment 매핑

start-ios

development

로컬 시뮬레이터/기기 실행은 APNs sandbox 경로를 사용합니다.

build-ios

production

릴리즈 빌드 생성은 production APNs environment를 사용합니다.

release-ios

production

스토어/TestFlight 릴리즈는 production APNs environment를 사용합니다.

@capacitor-community/fcm을 사용할 때 Xcode에 firebase-ios-sdk를 직접 추가하지 마세요. 직접 추가한 Firebase Swift Package product는 플러그인이 요구하는 Firebase 의존성 버전과 충돌할 수 있습니다.

왜 Capacitor 플러그인을 두 개 쓰나요?

@capacitor/push-notifications는 권한, 네이티브 등록, 알림 클릭 이벤트, Android channel 같은 OS push bridge를 담당합니다. @capacitor-community/fcm은 FCM.getToken() 같은 Firebase 전용 token 접근을 담당합니다. Akan은 FCM을 provider로 사용하므로 네이티브 앱에서는 둘 다 필요합니다.

@capacitor/push-notifications

알림 권한, 네이티브 등록, 알림 액션/클릭 리스너, 표시된 알림, Android notification channel에 사용합니다.

@capacitor-community/fcm

Firebase Messaging token 접근에 사용합니다. Android와 iOS 서버 발송을 같은 Firebase Admin send({ token }) 계약으로 맞춥니다.

Deep Link Setup

Deep link는 앱 바깥에서 CSR route를 여는 기능입니다. 앱 전용 URL은 schemes를 쓰고, 검증된 HTTPS 링크는 domains를 씁니다. Push notification 클릭도 data.url을 통해 같은 라우팅 경로를 사용합니다.

Deep link는 기능 이름이고, scheme과 domain은 그 기능을 구현하는 대표적인 두 방식입니다. shop://orders/1 같은 scheme link는 테스트가 쉽고 앱 전용입니다. https://shop.example.com/orders/1 같은 domain link는 iOS/Android 검증 설정이 필요하지만 일반 웹 링크처럼 동작하므로 공유, 이메일, push notification URL에 더 적합합니다.

apps/myapp/akan.config.ts

schemes: shop://orders/1 같은 앱 전용 URL입니다. 테스트하기 쉽지만 도메인 검증 링크는 아닙니다.

domains: https://shop.example.com/orders/1 같은 검증된 HTTPS 링크입니다. iOS는 apple-app-site-association, Android는 assetlinks.json을 사용합니다.

Verify Setup

빌드 성공에서 멈추지 마세요. 플러그인 사용 가능 여부, 네이티브 파일 위치, 권한 prompt, push token 생성, 서버 발송, 클릭 라우팅까지 실제 기능 표면을 확인해야 합니다.

Plugin available: 콘솔에 plugin is not implemented가 나오면 JS package는 있지만 네이티브 플러그인이 링크되지 않은 상태입니다. app package.json을 확인하고 sync/build를 다시 실행하세요.

Android push: package name, app/google-services.json, Google Services Gradle 설정, 알림 권한, Firebase 프로젝트 일치를 확인하세요.

iOS push: 실기기 테스트, aps-environment entitlement, APNs key 업로드, provisioning profile, GoogleService-Info.plist target membership을 확인하세요.

Click routing: url: /some/path가 포함된 알림을 보내고, 클릭했을 때 기대한 CSR route가 열리는지 확인하세요.