Android 빌드

이 플러그인의 설치 단계와 전체 마크다운 가이드가 포함된 설정 프롬프트를 복사하세요.

Capgo의 전용 인프라로 Android 앱을 빌드하고 Google Play Store에 제출하세요.

배우게 될 내용

Capgo Native Build를 통해 앱을 업로드하는 방법을 배웁니다.
Capgo Native Build에 대한 인증 정보를 설정하는 방법을 배웁니다.

사전 요구사항

활성화된 Google Developer 계정이 필요합니다.
Android Studio가 설치되어 있어야 합니다.
Android Studio에서 앱이 정상적으로 빌드되어야 합니다.

이 모든 과정을 직접 할 필요는 없습니다. Capgo의 onboarding이 Android 서명 자격 증명(keystore + Google Play 서비스 계정)을 대신 생성하고 설정해 줍니다. 이 방법을 권장합니다:

bunx @capgo/cli@latest build init --platform android

아래 수동 안내는 자격 증명을 직접 설정하려는 분, 또는 Capgo가 내부에서 정확히 어떻게 동작하는지 이해하려는 분만을 위한 것입니다.

첫 번째 수동 빌드

Capgo로 앱 빌드를 시작하기 전에, 먼저 설정하고 수동으로 첫 Android 빌드를 진행해야 합니다. 수동 빌드를 먼저 하면 다음과 같은 장점이 있습니다:

이후 Capgo 빌드에 사용할 자격 증명을 준비하게 됩니다.
Play Store Console에 레코드를 생성하게 됩니다.

Android Studio로 앱 수동 빌드하기

Capgo로 앱 빌드를 시작하기 전에, Android Studio로 앱을 수동으로 빌드해야 합니다.

Android Studio 열기

실행 bunx cap open android Android Studio 프로젝트를 열려면
클릭하세요 Build -> Generate Signed App Bundles / APKs
선택 Android App Bundle 를 클릭합니다. Next

Keystore 생성하기

현재 keystore 파일이 없습니다. 이 파일은 앱에 서명하는 데 사용되며, Google이 앱을 빌드한 사람이 본인임을 알 수 있게 해줍니다. 이 파일을 생성하려면 Android Studio에서 제공하는 GUI 방식을 사용하겠습니다. 명령줄로 하는 방법도 있지만, 이번 튜토리얼에서는 다루지 않습니다.

클릭하세요 Create new
Key Store 경로 입력

이 반드시 저장해야 합니다 - 나중에 사용됨
Key Store 비밀번호 설정

Key Store와 Key Alias에 동일한 비밀번호를 사용하는 것을 권장합니다.

이 반드시 저장해야 합니다 - 나중에 사용하게 됩니다
나머지 양식을 작성하세요
1. Key Alias를 그대로 유지하세요 (key0)
2. 인증서 세부 정보를 입력하세요. 가짜 정보로 채워 두었지만, 본인의 실제 정보로 입력해야 합니다.
클릭하세요 OK

수동 빌드 마무리하기

keystore의 모든 세부 정보가 올바르게 입력되었는지 확인한 후 클릭하세요 Next
다음을 선택하세요: release 빌드 변형을 선택하고 클릭하세요 Create
빌드가 성공하면 다음 화면이 표시됩니다
1. 이 팝업은 빌드가 성공했음을 나타냅니다.
2. 다음을 클릭하세요: locate 버튼 - 파일 탐색기가 열리고, 거기서 빌드를 확인할 수 있습니다.
파일 탐색기에서 빌드가 보이는지 확인하세요

Play Store Console에서 앱 생성하기

다음으로 이동: Google Play Console
올바른 개발자 계정 선택
클릭하세요 Create app
앱 이름과 언어 선택
앱 카테고리를 선택하고 유료/무료 여부를 지정하세요
이용 약관에 동의하세요

동의하기 전에 이용 약관을 꼭 읽어보세요.
클릭하세요 Create

내부 테스트 그룹 생성하기

앱을 만들었으니 이제 내부 테스트 그룹을 만들 수 있습니다. Play Store에 앱을 전체 공개로 출시하지는 않을 것이므로 내부 테스트 그룹을 만들어야 합니다.

다음으로 이동: internal testing 클릭하세요 Test and release -> Testing -> Internal testing
클릭하세요 Testers
클릭하세요 Create email list
이메일 목록 이름 지정
테스터 이메일 주소 추가
누르고 Enter 를 클릭합니다. Save
클릭하세요 Create group
새 목록이 선택되어 있는지 확인하고 클릭 Save

내부 테스트 그룹에 앱 업로드하기

내부 테스트 그룹을 생성했으므로, 이제 해당 그룹에 앱을 업로드할 수 있습니다.

다음으로 이동: Test and release -> Testing -> Internal testing
다음을 클릭하세요: Releases 버튼을 클릭하세요
클릭하세요 Create new release
클릭하세요 Upload
AAB 파일 선택

Android Studio로 직접 빌드한 AAB 파일을 선택했는지 확인하세요. 이 파일이 Capgo 빌드에 사용할 keystore와 동일한 keystore를 사용하지 않으면 Capgo Native Build가 실패합니다.
AAB 파일 업로드가 완료될 때까지 대기
클릭하세요 Next
오류 수정

개인적으로는 이 단계에서 이 오류를 확인했습니다.

아직 전화번호 인증을 완료하지 않았기 때문입니다. 인증을 마친 후 튜토리얼을 계속 진행하겠습니다.
클릭하세요 Save and publish 이렇게 하면 앱이 내부 테스트 그룹에 게시됩니다.
게시 확인
앱이 게시되었는지 확인
임시 앱 이름 가져오기

내부 테스트 그룹 초대 수락하기

앱을 내부 테스트 그룹에 업로드했으므로, 이제 내부 테스트 그룹 초대장을 수락할 수 있습니다.

다음으로 이동: Test and release -> Testing -> Internal testing
클릭하세요 Testers
클릭하세요 Copy link
링크를 휴대폰으로 보낸 뒤, 브라우저에서 열고 다음을 클릭하세요 Accept
초대가 수락되었는지 확인한 후 “Play Store에서 다운로드”를 클릭하세요
앱 설치
1. Android Studio를 사용하기 전에 앱을 설치한 적이 있다면, 다음 uninstall 버튼을 클릭하세요
2. 다음을 클릭하세요: install 버튼을 클릭하세요
3. 앱을 열고 성공적으로 다운로드되었는지 확인하세요
Play Store에서 앱이 표시되지 않으면, Play Store에서 올바른 계정이 선택되었는지 확인하세요.

Capgo Native Build 설정하기 (Android)

이제 Capgo Native Build 설정을 시작할 준비가 되었습니다. 축하합니다 🎉!

요구 사항	플래그	설명	필수
Keystore 파일	`--keystore <path>`	파일 경로 `.jks`/`.keystore` APK/AAB 서명에 사용되는 파일.	지원
Keystore 별칭	`--keystore-alias <alias>`	Keystore 내 키의 alias 이름.	지원
Keystore 키 비밀번호	`--keystore-key-password <password>`	키 비밀번호입니다. 키와 스토어 비밀번호가 같다면 하나만 입력해도 됩니다.	아래 참고 사항을 확인하세요
Keystore 저장소 비밀번호	`--keystore-store-password <password>`	키스토어 비밀번호입니다. 키와 스토어 비밀번호가 같다면 하나만 입력해도 됩니다.	아래 참고 사항을 확인하세요
Google Play 서비스 계정	`--play-config <path>`	Play Store 업로드용 JSON 서비스 계정 파일입니다.	지원

bunx @capgo/cli@latest build credentials save --platform android \
  --keystore ./path/to/keystore.jks \
  --keystore-alias "your-alias" \
  --keystore-key-password "key-password" \
  --keystore-store-password "store-password" \
  --play-config ./play-store-service-account.json

Keystore, keystore 비밀번호, keystore 키 비밀번호, keystore alias

만약 다음 수동 build 안내를 따랐다면, keystore가 이미 생성되어 있어야 합니다. 따르지 않았다면, 안내에 따라 keystore를 생성해 주세요.

Google Play 서비스 계정

Google Play 서비스 계정 생성은 수동으로 진행해야 하는 복잡한 과정입니다. 하지만 앱을 Google Play에 업로드하려면 반드시 필요합니다. 다음 사항에 유의하세요:

귀하 반드시 다음의 권한이 Developer Account 소유자여야 합니다. 그렇지 않으면 서비스 계정을 설정할 수 없습니다.
Google Play 계정과 별도로 새 Google Cloud Project를 만들어야 합니다.

시작해 보겠습니다.

다음으로 이동: Google Cloud Console
프로젝트 선택기를 클릭하세요
이미 프로젝트가 있다면 선택하세요. 없다면 새 프로젝트를 만드세요:

아래 스크린샷은 예시입니다. 프로젝트에 맞는 이름을 사용하세요.
1. 클릭하세요 New project
2. 프로젝트 이름을 입력하고 클릭하세요 Create
3. 올바른 프로젝트를 선택했는지 확인하세요
검색창을 클릭하고 다음을 검색해 보세요: service accounts 그리고 클릭하세요
다음 항목을 클릭하세요: Create service account
서비스 계정 양식을 작성하고 다음을 클릭하세요 Done
1. 이름은 다음으로 설정하는 것을 권장합니다 Capgo Native Build Service Account
2. 서비스 계정 ID는 다음으로 설정하는 것을 권장합니다 capgo-native-build-service-acc
3. 설명은 입력하지 않아도 되지만, 다음으로 채우는 것을 권장합니다 Allows Capgo Native Build to build and submit the app to the Play Store
새로 생성된 서비스 계정을 클릭하세요 이제 목록에 새로 생성된 서비스 계정이 표시됩니다. 해당 계정을 클릭하세요.

이 이메일 주소도 복사해 두세요. 나중에 필요합니다.
다음을 클릭하세요: Keys 탭
클릭하세요 Add Key 및 Create new key
클릭하세요 JSON 및 Create

클릭하면 Create 새 키가 생성되고 JSON 파일이 로컬 머신으로 다운로드됩니다.
JSON 파일을 안전한 곳에 저장해야 합니다. 이 파일은 반드시 나중에 사용됩니다.
JSON 파일 다운로드 JSON 파일이 자동으로 다운로드되었어야 합니다. 클릭하면 close 창을 닫을 수 있습니다.

서비스 계정에 Play Store API 권한 부여하기

새로 생성된 서비스 계정에는 아직 Play Store API 권한이 없습니다. 권한을 부여하려면 Play Store Console로 이동하세요.

다음으로 이동: Google Play Console
올바른 개발자 계정 선택
클릭하세요 Users and permissions
클릭하세요 Invite new users
서비스 계정의 이메일 주소 복사
다음으로 이동: Account permissions 필요한 최소 권한을 부여하세요:
- 다음에서 App permissions, 앱에 대한 액세스 권한을 부여하세요.
- 다음에서 Releases, 활성화하세요 Create, edit, and roll out releases.
- 워크플로우에서 Play App Signing을 사용하는 경우, 관련 서명 권한을 활성화하세요.
- 확실하지 않다면, 사용하세요 Admin 설정 시에만 사용하고 이후에는 권한을 줄이세요.
클릭하세요 Invite user
초대 확인
사용자가 초대되었는지 확인

자격 증명 저장하기

이제 자격 증명을 저장하고 첫 번째 빌드를 실행할 준비가 되었습니다. 다음 명령으로 자격 증명을 저장할 수 있습니다:

bunx @capgo/cli@latest build credentials save --platform android \
  --keystore ./path/to/keystore.jks \
  --keystore-alias "your-alias" \
  --keystore-key-password "key-password" \
  --keystore-store-password "store-password" \
  --play-config ./play-store-service-account.json

CI/CD 설정 (GitHub Actions)

이미 완료했다면 Keystore, keystore 비밀번호, keystore 키 비밀번호, keystore alias 및 Google Play 서비스 계정, CI/CD에 필요한 모든 것이 이미 준비되어 있습니다. 이 섹션은 해당 값을 GitHub Actions 시크릿 및 환경 변수로 전달하는 방법만 다룹니다.

1) 자격 증명 파일을 단일 줄 base64로 변환

# Android keystore (.jks or .keystore)
base64 -i ./path/to/keystore.jks | tr -d '\n' > keystore_base64.txt

# Google Play service account JSON
base64 -i ./play-store-service-account.json | tr -d '\n' > play_config_base64.txt

2) 저장소 시크릿 생성

다음에서 GitHub > Repository > Settings > Secrets and variables > Actions, 추가:

Secret 이름	값
`CAPGO_TOKEN`	Capgo API 토큰
`APP_ID`	Capgo 앱 ID (예시: `com.example.app`)
`ANDROID_KEYSTORE_FILE`	내용 `keystore_base64.txt`
`KEYSTORE_KEY_ALIAS`	Keystore alias 출처 Keystore, keystore 비밀번호, keystore 키 비밀번호, keystore alias
`KEYSTORE_KEY_PASSWORD`	Keystore 키 비밀번호
`KEYSTORE_STORE_PASSWORD`	Keystore 저장소 비밀번호
`PLAY_CONFIG_JSON`	내용 `play_config_base64.txt`

3) GitHub Actions 워크플로에서 환경 변수 사용

name: Android Cloud Build

on:
  workflow_dispatch:
  push:
    branches: [main]

jobs:
  android-build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: oven-sh/setup-bun@v2
        with:
          bun-version: latest
      - name: Request Android build with Capgo
        run: bunx @capgo/cli@latest build request ${{ secrets.APP_ID }} --platform android
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
          ANDROID_KEYSTORE_FILE: ${{ secrets.ANDROID_KEYSTORE_FILE }}
          KEYSTORE_KEY_ALIAS: ${{ secrets.KEYSTORE_KEY_ALIAS }}
          KEYSTORE_KEY_PASSWORD: ${{ secrets.KEYSTORE_KEY_PASSWORD }}
          KEYSTORE_STORE_PASSWORD: ${{ secrets.KEYSTORE_STORE_PASSWORD }}
          PLAY_CONFIG_JSON: ${{ secrets.PLAY_CONFIG_JSON }}

빌드 실행하기

축하합니다 🎉! 이제 첫 번째 빌드를 실행할 준비가 되었습니다.

실행:

bunx @capgo/cli@latest build request com.example.app --platform android

이제 빌드 프로세스가 시작됩니다 🍾🥂

Play 릴리스 검토 제출

기본적으로 Android 릴리스 빌드는 Google Play에 업로드되며, Play Console에서 출시를 완료할 때까지 비활성 상태로 남을 수 있습니다. CI 릴리스에서 Play 출시를 자동으로 제출하려면 다음을 전달하세요: --submit-to-store-review 릴리스 빌드와 함께:

npx @capgo/cli@latest build request com.example.app \
  --platform android \
  --build-mode release \
  --submit-to-store-review \
  --android-track production \
  --store-release-name "1.2.3" \
  --store-release-notes "General improvements" \
  --store-release-notes-locale "en-US=General improvements" \
  --store-release-notes-locale "nl-NL=Algemene verbeteringen" \
  --store-release-notes-locale "fr-FR=Ameliorations generales"

일반 upload 경로와 동일한 Google Play 서비스 계정 설정이 필요합니다 (PLAY_CONFIG_JSON CI에서 사용하거나 로컬에 저장한 Android 자격 증명). --store-release-name 는 Google Play 릴리스 노트로 사용됩니다 version_name. --store-release-notes 는 대체 Play changelog이며, 각 --store-release-notes-locale "locale=notes" entry는 해당 로케일용 로컬라이즈된 Play 변경 이력을 작성합니다. Capgo는 Play 릴리스를 다음과 같이 전송합니다 completed 오버라이드하지 않는 한 --android-release-status; Play Console에서 Managed publishing이 활성화되어 있으면, 승인 후에도 Google이 수동 게시를 기다릴 수 있습니다.

Android 빌드에서 계속하기

사용 중이라면 Android 빌드 CI/CD 자동화를 계획하려면, 다음을 연결하세요 Capgo CI/CD 설정하기 Capgo CI/CD의 제품 워크플로우용, Capgo Native Build Capgo Native Builds의 제품 워크플로우용, Capgo 연동 서비스 Capgo Integrations의 제품 워크플로우용, CI/CD 통합 CI/CD Integration의 구현 세부 사항은, 그리고 GitHub Actions 연동 GitHub Actions Integration의 구현 세부 사항을 참고하세요.