[iOS] capacitor를 이용하여 React 웹 앱을 iOS app으로 변환하기

정글 4기를 마치고 오랜 시간이 흘렀고, 팀원들과 다시 뭉쳐서 프로젝트를 더 develop 하고자 하였다.

그 일환으로 이전에 포스터세션에서 '앱으로 만들어서 마켓에 출시'하는 것을 추천해주신 분이 계셨다.

우리도 그 조언을 적극 반영하여 mvp 기능만 있었던 우리의 웹 앱을 좀 더 발전시켜 최종적으로 App Store에 배포하는 것을 목표로 삼게 되었다.

그래서.. 지금부터 일련의 과정을 공유해보고자 한다.

첫 심사를 마치고 난 다음에 작성하는 글이기 때문의 과정 중 생략되거나 미처 적지 못한 것이 있을 수 있음!!

pwa to iOS

먼저 우리는 빠른 시간 안에, 코드의 수정 없이 최대한 기존의 코드들을 이용해서 배포를 진행하고 싶었기 때문에 단순하게 react app을 iOS에서 돌릴 수 있도록 native하게 convert 해주는 프레임워크가 필요했다.

why Capacitor?

우리가 원하는 convert가 원활하게 수행되기 위해서는 대표적으로 capacitor와 cordova가 있었는데, 결론적으로 말하자면 개발 접근성의 측면에서 capacitor가 더 좋았다고 판단했기 때문에 capacitor를 선택하게 되었다.

다음은 gpt가 말한 capacitor를 사용하는 이유이다.

1. 최신 웹 기술 지원:
   Capacitor는 최신 웹 기술을 지원하여 React, Angular, Vue 등과 같은 프레임워크와 쉽게 통합됩니다. 이는 최신 웹 애플리케이션 개발자들이 이미 익숙한 도구와 기술을 그대로 사용할 수 있게 해줍니다.

2. 네이티브 기능 접근:
   Capacitor는 네이티브 기능에 접근할 수 있는 API를 제공하여, 카메라, 파일 시스템, 위치 서비스 등 모바일 디바이스의 하드웨어와 소프트웨어 기능을 활용할 수 있습니다. 이는 PWA가 제공하지 못하는 네이티브 앱 수준의 기능성을 가능하게 합니다.

3. 플랫폼 간 일관성:
   Capacitor는 단일 코드베이스로 iOS, Android, 웹을 포함한 여러 플랫폼에 애플리케이션을 배포할 수 있게 합니다. 이는 개발 및 유지보수에 들어가는 시간과 비용을 절감합니다.

4. PWA와 네이티브 앱의 장점 결합:
   Capacitor를 사용하면 웹 애플리케이션의 업데이트가 간편하고, 배포 주기가 짧다는 장점과 네이티브 애플리케이션의 성능과 기능성을 결합할 수 있습니다.

5. 직관적인 API:
   Capacitor는 직관적인 API를 제공하여 개발자들이 쉽게 네이티브 기능을 호출하고 사용할 수 있게 합니다. 이는 복잡한 네이티브 코드 작성을 최소화하고, 웹 개발 경험을 최대한 활용할 수 있게 합니다.

이후에는 GPT가 안내해준 대로 기존의 프로젝트 폴더에서 여러가지를 설치해주는 것으로부터 시작하였다.

세부적인 절차는 다음과 같다.

procedures to release iOS application

1. PWA를 iOS 앱으로 변환하기

2. iOS 애플리케이션 설정 및 구성

Xcode에서 iOS 프로젝트를 열고 설정을 완료해야 한다.

1. Xcode 설치
   • Xcode는 macOS에서 사용할 수 있으며, Mac App Store에서 다운로드할 수 있다.

2. 앱 아이콘 및 런치 스크린 설정
   • 앱 아이콘: Assets.xcassets에서 아이콘을 설정한다.
   • 런치 스크린: LaunchScreen.storyboard에서 런치 스크린을 설정한다.

3. 앱 설정
   • Signing & Capabilities 탭에서 애플 개발자 계정을 연결하고, 팀을 선택한다.
   • Bundle Identifier를 적절히 설정한다.
   • 필요한 Capabilities (예: 푸시 알림, 백그라운드 모드 등)를 추가한다.

3. 앱 테스트 및 빌드

1. 시뮬레이터에서 테스트
   Xcode에서 iOS 시뮬레이터를 선택하고 애플리케이션을 실행해 본다.

2. 실제 디바이스에서 테스트
   실제 iOS 디바이스에 애플리케이션을 설치하고 테스트한다. 이를 위해 애플 개발자 계정이 필요하다.

4. 앱스토어에 제출하기

1. 애플 개발자 프로그램 가입
   애플 개발자 프로그램에 가입한다. 연간 요금이 있으며, 애플 개발자 웹사이트에서 가입할 수 있다.

2. 앱스토어 연결
   • App Store Connect에 로그인한다.
   • 새로운 앱을 생성한다.
   • 앱 정보, 스크린샷, 설명 등을 입력한다.

3. 앱 아카이브 및 제출
   • Xcode에서 Product -> Archive를 선택하여 앱을 아카이브한다.
   • 아카이브가 완료되면 Organizer 창이 열리고, 여기서 Distribute App을 선택하여 앱을 제출힌다.

4. 앱 심사
   애플의 심사 과정을 거친다. 이 과정은 며칠이 걸릴 수 있으며, 심사 결과는 이메일로 통보된다.

5. 앱 출시
   심사를 통과하면 앱스토어에 앱이 출시된다.

PWA를 iOS 앱으로 변환하기

1. 프로젝트 설정:
   npm install @capacitor/core @capacitor/cli npx cap init [appName] [appId]

2. 플랫폼 추가:
   npx cap add ios npx cap add android

3. 웹 애플리케이션 빌드 및 복사:
   npm run build npx cap copy

4. 네이티브 IDE에서 열기:
   npx cap open ios npx cap open android

얼마나 간단한가!

우리가 해야할 것은 그저 capacitor를 npm install 하고, capacitor를 통해 프로젝트를 초기화 한 후 변환할 플랫폼을 추가하고 빌드하고 복사하여 실행하면 되는 것이었다.

여기서 appName과 appId는 각각 다음을 뜻했다.

• 프로젝트 이름 (name): 사용자에게 보여지는 애플리케이션 이름. 예: MyPWAApp.
• 프로젝트 ID (id): 고유 식별자, 네이티브 애플리케이션의 번들 식별자로 사용. 예: com.example.mypwaapp.

npx cap add ios를 하고나면 폴더 최상단에 ios폴더가 생기고, 설정했던 프로젝트 이름 대로 폴더가 하위에 생기게 된다.

사실 이 폴더들과 그 안의 항목들에 대해서 더 살펴보았다면 후술할 시행착오들을 덜 겪었을 것 같은데, 그 당시에는 그러지 못했었다. 그래서 지금이라도 살펴보자면 다음과 같다.

1. ios 폴더

ios 폴더는 프로젝트 루트 디렉터리에 생성되며, Xcode를 통해 빌드하고 실행할 수 있는 네이티브 iOS 프로젝트를 포함하고 있다.

폴더 구조 개요

• App
  • App.xcodeproj: Xcode 프로젝트 파일이다.
  • App.xcworkspace: CocoaPods 등을 사용할 때 생성되는 워크스페이스 파일이다.
  • App (디렉터리)
    • AppDelegate.swift: 앱의 라이프사이클 이벤트를 관리하는 파일이다.
    • Info.plist: 앱의 메타데이터와 설정 정보를 담고 있다.
    • Main.storyboard: 앱의 기본 UI를 정의하는 스토리보드 파일이다.
    • ViewController.swift: 메인 뷰 컨트롤러로, 웹뷰를 초기화한다.
    • Assets.xcassets: 이미지 및 아이콘 리소스를 포함한다.
    • LaunchScreen.storyboard: 앱 실행 시 표시되는 런치 스크린을 정의한다.
• Podfile: CocoaPods 종속성을 관리하는 설정 파일이다.
• Podfile.lock: 현재 설치된 종속성의 버전 정보를 기록한 파일이다.
• Pods: CocoaPods를 통해 설치된 라이브러리가 저장되는 디렉터리이다.
• capacitor.config.json: iOS 플랫폼에 대한 Capacitor 설정 파일이다.
• capacitor-cordova-ios-plugins: Cordova 플러그인이 있는 경우 생성되는 디렉터리이다.

2. 주요 파일 및 폴더 상세 설명

2.1 AppDelegate.swift

• 역할: 앱의 생명주기를 관리하며, 앱이 시작되거나 종료될 때 필요한 처리를 수행한다.
• 내용: Capacitor의 초기화 코드와 푸시 알림 등의 이벤트 핸들러가 포함될 수 있다.

2.2 Info.plist

• 역할: 앱의 번들 식별자, 버전 정보, 권한 요청 등 중요한 설정을 담고 있다.
• 내용: 카메라, 위치 정보 등 민감한 데이터에 접근하려면 해당 권한을 이 파일에 추가해야 한다.

2.3 Main.storyboard

• 역할: 앱의 UI를 시각적으로 구성하는 곳이다.
• 내용: 기본적으로 Capacitor는 전체 화면 웹뷰를 사용하므로, 이 스토리보드에는 웹뷰가 설정되어 있다.

2.4 ViewController.swift

• 역할: 메인 뷰 컨트롤러로, 웹뷰를 초기화하고 로드한다.
• 내용: loadWebView() 메서드를 통해 웹 애플리케이션을 로드한다.

2.5 Assets.xcassets

• 역할: 앱에서 사용하는 이미지 리소스를 관리한다.
• 내용: 앱 아이콘, 런치 이미지 등을 이곳에 추가한다.

2.6 LaunchScreen.storyboard

• 역할: 앱 실행 시 표시되는 초기 화면을 구성한다.
• 내용: 스플래시 스크린이나 로딩 화면을 디자인할 수 있다.

2.7 Podfile 및 Podfile.lock

• Podfile
  • 역할: CocoaPods를 사용하여 종속성을 관리하는 설정 파일이다.
  • 내용: 필요한 라이브러리와 그 버전을 명시한다.
• Podfile.lock
  • 역할: 현재 설치된 종속성의 정확한 버전 정보를 기록한다.
  • 내용: 팀원 간 종속성 버전을 일치시키기 위해 사용한다.

2.8 Pods 디렉터리

• 역할: CocoaPods를 통해 설치된 모든 라이브러리가 저장된다.
• 주의사항: 일반적으로 버전 관리를 하지 않는다.

2.9 capacitor.config.json

• 역할: iOS 플랫폼에 대한 Capacitor 설정을 담고 있다.
• 내용: 앱 ID, 앱 이름, 서버 설정 등 다양한 옵션을 지정한다.

2.10 capacitor-cordova-ios-plugins

• 역할: Cordova 플러그인을 사용하는 경우, 해당 플러그인의 네이티브 코드가 저장된다.
• 내용: 플러그인별로 분류되어 관리된다.

3. 추가적인 중요 파일 및 설정

3.1 Signing & Capabilities (Xcode 설정)

• 역할: 앱의 배포를 위해 필요한 서명 및 권한 설정을 관리한다.
• 내용: 푸시 알림, 인앱 결제 등 추가 기능을 사용할 때 Capability를 추가한다.

3.2 Build Settings (Xcode 설정)

• 역할: 빌드 과정에서 사용되는 설정을 관리한다.
• 내용: 컴파일러 옵션, 경로 설정, 라이브러리 링크 등을 조정한다.

vscode에서 위의 과정을 다 진행하고 나면, npx cap open ios를 통해 xcode를 띄워준다.

여기까지 마무리 되었다면 첫 번째 단계인, PWA를 iOS 앱으로 변환하기 까지가 완료 되었다고 볼 수 있다.

하지만 우리가 가장 마지막에 shell에 입력했던 커맨드는 open ios였다. 즉 xcode를 open만 해줄 뿐 그 다음부터는? xcode에서 진행하게 된다.

처음에 xcode에서 무엇을 진행해야할지 몰라서, 가장 확실해보이는 play 버튼?을 눌렀다.

예상대로 어플리케이션을 실행하는 버튼이 맞았다. 하지만 빌드를 진행하고 앱을 실행하려는데, build 중 오류가 발생하였다.

/Users/pongpongi/Jungle/namanmoo_project/ModuGisang/frontend/ios/App/App/Assets.xcassets: None of the input catalogs contained a matching stickers icon set or app icon set named  "AppIcon"

iOS 어플리케이션 설정 및 구성

capacitor를 통해서 initialize를 하고 난 다음에 기본적으로 작업해주어야 할 것들이 여러가지 있다.

바로 앱 아이콘과 런치스크린을 설정해주는 것이다.

AppIcon 세트가 없으면 Xcode는 앱을 빌드할 때 필요한 아이콘 파일을 찾을 수 없어서 오류가 발생했던 것이다.

AppIcon 세트를 추가하는 과정은 다음과 같다.

1. Assets.xcassets 폴더에 AppIcon 세트가 있는지 확인.
2. 없다면 새로운 AppIcon 세트를 생성하고 아이콘 파일 추가.
3. 타겟 설정에서 App Icons Source가 AppIcon으로 설정되었는지 확인.

그리고 정상적으로 등록이 되었다면 다음과 같이 나올 것이다.

다음은 Launch Screen 설정이다. 어쩌면 AppIcon 설정과 비슷했던 것 같다.

1. LaunchScreen.storyboard 파일에 있는 view controller의 속성을 편집한다.
2. Object Library에서 Image View를 드래그하여 view Controller의 뷰에 추가한다.
3. Image View를 선택하고 오른쪽 Attributes Inspector에서 Image 속성을 설정한다.
4. 이미지를 프로젝트에 추가하려면 Assets.xcassets에 이미지를 드래그 앤 드롭한다.
5. 다양한 화면 크기에 대응하기 위해 Auto Layout 제약조건을 설정한다.
6. Image View를 선택한 상태에서 하단의 Add New Constraints 버튼을 클릭한다.

Asset에 정상적으로 등록된 launchScreen은 다음과 같다.

LaunchScreen.storyboard는 다음과 같다.

여기까지만 한다면, 빌드하고 시뮬레이터에서 실행은 정상적으로 될 것이다.

시뮬레이터와 실제 기기에서 테스트하기 위한 설정이 약간 다른데, 시뮬레이터의 경우는 `Bundle ID`만 설정되어 있으면 빌드와 실행이 가능하고 프로비저닝 프로파일이 불필요하다.

하지만 실제 기기에서 테스트 하기 위해서는 Bundle ID와 Provisioning Profile 둘 다 필요하다.

배포하는 과정은 추후에 알아보도록 하겠다.